Class CMMTunerUtility

class CMMTunerUtility : public CBase;

Description

The MMF Tuner API is present to allow clients to control the tuner hardware present on a device.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CMMTunerUtility - The MMF Tuner API is present to allow clients to control the tuner hardware present on a device

Members

Defined in CMMTunerUtility:
CancelNotifyChange(), CancelNotifySignalStrength(), CancelNotifyStereoChange(), CancelRetune(), Close(), CustomCommandAsync(), CustomCommandSync(), CustomInterface(), ESearchDirectionDown, ESearchDirectionUp, ETunerAccessPriorityAlarm, ETunerAccessPriorityBackground, ETunerAccessPriorityNormal, ETunerAccessPrioritySystem, ETunerBandAm, ETunerBandDab, ETunerBandDvb, ETunerBandFm, ETunerBandJapaneseFm, ETunerBandLw, ETunerNoBand, ETunerStateActive, ETunerStatePlaying, ETunerStateRecording, ETunerStateRetuning, ForceMonoReception(), GetCapabilities(), GetChannel(), GetChannelRange(), GetFlightMode(), GetForcedMonoReception(), GetFrequency(), GetFrequencyBandRange(), GetMaxSignalStrength(), GetPriority(), GetRdsTunerUtilityL(), GetSignalStrength(), GetSquelch(), GetState(), GetTunerAudioPlayerUtilityL(), GetTunerAudioRecorderUtilityL(), GetTunerScannerUtilityL(), IsAntennaAttached(), IsStereoSignal(), NewL(), NotifyChange(), NotifySignalStrength(), NotifyStereoChange(), NotifyTunerControl(), ReleaseTunerControl(), RequestTunerControl(), SetPriority(), SetSquelch(), StationSeek(), StationSeek(), TSearchDirection, TTunerAccessPriority, TTunerBand, TTunerState, Tune(), Tune(), TunersAvailable(), ~CMMTunerUtility()

Inherited from CBase:
Delete(), Extension_(), operator new()

static IMPORT_C CMMTunerUtility *NewL(MMMTunerObserver &aObserver, TInt aTunerIndex, TTunerAccessPriority aAccessPriority=ETunerAccessPriorityNormal);

Description

Factory function to create a new instance of the Tuner. Tuner access priority setting is required to ensure that applications such as alarms using the radio as an alarm sound are not prevented from doing so by other clients. Priority setting is needed for audio output when accessing the sound device. Tuner is ready for use on return from this function.

Parameters

MMMTunerObserver &aObserver The observer object for receiving async completion callbacks TInt aTunerIndex An index from 0 to TunersAvailable() - 1 specifying the tuner device to use. TTunerAccessPriority aAccessPriority Tuner access priority value

Return value

CMMTunerUtility * A pointer and ownership of the fully constructed CMMTunerUtility object

Leave codes

KErrNoMemory Out of memory KErrNotFound The specified tuner or tuner controller is not present

virtual IMPORT_C ~CMMTunerUtility();

Description

static IMPORT_C TInt TunersAvailable();

Description

Determines the number of tuners available on a device.

Return value

TInt Count of tuners present on the device.

static IMPORT_C TInt GetCapabilities(TInt aTunerIndex, TTunerCapabilities &aCaps);

Description

Get the capabilities of the tuner on the device

Parameters

TInt aTunerIndex The index of the tuner whose capabilities are to be gathered TTunerCapabilities &aCaps The capabilities object to fill

Return value

TInt A standard system error code

IMPORT_C CMMTunerAudioPlayerUtility *GetTunerAudioPlayerUtilityL(MMMTunerAudioPlayerObserver &aObserver);

Description

Factory function to create a new Tuner Audio Player utility. Note that only one audio player utility may be created per instance of CMMTunerUtility. Multiple instances will result in an error of KErrAlreadyExists when InitializeL() is called.

Parameters

MMMTunerAudioPlayerObserver &aObserver The observer of the player utility to receive asychronous completion and notifiction callbacks.

Return value

CMMTunerAudioPlayerUtility * A new tuner audio player utility.

Leave codes

KErrNoMemory Out of memory KErrNotSupported If the given tuner doesn't support audio playback.

IMPORT_C CMMTunerAudioRecorderUtility *GetTunerAudioRecorderUtilityL(MMMTunerAudioRecorderObserver &aObserver);

Description

Factory function to create a new Tuner Audio Recorder utility. Note that only one audio recorder utility may be created per instance of CMMTunerUtility. Multiple instances will result in an error of KErrAlreadyExists when InitializeL() is called.

Parameters

MMMTunerAudioRecorderObserver &aObserver The observer of the player utility to receive asychronous completion and notifiction callbacks.

Return value

CMMTunerAudioRecorderUtility * A new tuner audio recorder utility.

Leave codes

KErrNoMemory Out of memory KErrNotSupported If the given tuner doesn't support audio recording.

IMPORT_C CMMRdsTunerUtility *GetRdsTunerUtilityL(MMMTunerObserver &aObserver);

Description

Factory function to create a new RDS Tuner utility. Note that only one RDS Tuner utility may be created per instance of CMMTunerUtility. If multiple instances are created their behaviour is undefined.

Parameters

MMMTunerObserver &aObserver The observer of the player utility to receive asychronous completion and notifiction callbacks.

Return value

CMMRdsTunerUtility * A new RDS Tuner Utility.

Leave codes

KErrNoMemory Out of memory KErrNotSupported If the given tuner doesn't support RDS.

IMPORT_C CMMTunerScannerUtility *GetTunerScannerUtilityL(MMMTunerObserver &aObserver);

Description

Factory function to create a tuner scanner utility. Note that only one Tuner Scanner utility may be created per instance of CMMTunerUtility. If multiple instances are created their behaviour is undefined.

Parameters

MMMTunerObserver &aObserver The observer of the player utility to receive asychronous completion and notifiction callbacks.

Return value

CMMTunerScannerUtility * A new tuner scanner utility.

Leave codes

KErrNoMemory Out of memory KErrNotSupported If the given tuner doesn't support station scanning.

Capability:

MultimediaDD

IMPORT_C TInt SetPriority(TTunerAccessPriority aAccessPriority);

Description

Set the current tuner access priority of this client. This priority is used to arbitrate between multiple tuner clients, determining who get control of the tuner.

A process requesting or using this method that has MultimediaDD capability will always have precedence over a process that does not have MultimediaDD.

Parameters

TTunerAccessPriority aAccessPriority The new priority to use.

Return value

TInt A standard system error code.

IMPORT_C TInt GetPriority(TTunerAccessPriority &aAccessPriority) const;

Description

Get the current tuner access priority of this client.

Parameters

TTunerAccessPriority &aAccessPriority A variable to which the current priority will be written.

Return value

TInt A standard system error code.

IMPORT_C TInt GetState(TUint32 &aState) const;

Description

Get the current state of the tuner.

Parameters

TUint32 &aState A variable to set with the current state. Bits set according to TTunerState.

Return value

TInt A standard system error code.

IMPORT_C TInt IsAntennaAttached(TBool &aAttached);

Description

Indicates if the external antenna is currently attached or not. The tuner capabilties should be queried to determine if the external antenna is required to use the tuner or not; A value of false returned here does not necessarily imply that the tuner cannot be used.

Parameters

TBool &aAttached When this function returns, this will contain ETrue if and only if an external antenna is attached.

Return value

TInt A standard system error code.

IMPORT_C TInt GetFlightMode(TBool &aFlightMode) const;

Description

Indicates if the device is currently in 'flight mode' or not. The tuner capabilities should be queried to determine in the tuner can be used in flight mode or not.

Parameters

TBool &aFlightMode On return, this will have been set to ETrue if and only if the device is in flight mode.

Return value

TInt A standard system error code.

IMPORT_C void Tune(TFrequency aFrequency, TTunerBand aBand);

Description

Tune the tuner to the required frequency specified in Hertz.

This is an asynchronous command and will result in a callback to MToTuneComplete. If no error has occured then the error code passed to the callback function will be KErrNone otherwise it will reflect the nature of the error.

If the session does not currently have control of the tuner, a request for control will be made. If control of the tuner is granted then MToTunerEvent will be invoked with an event type of EControlEvent and an error of KErrNone.

Once control of the tuner has been granted, it will be retained until either a call to ReleaseTunerControl, or the session is preempted in which case there will be a callback to MToTunerEvent with an event type EControlEvent with error value KErrAccessDenied.

A callback to MToTuneComplete with an error value of KErrNone indicates that the tuning has completed successfully. If control of the tuner cannot be granted at present the error will be KErrAccessDenied

Parameters

TFrequency aFrequency The frequency to tune to TTunerBand aBand The band to which aFrequency belongs

IMPORT_C void Tune(TChannel aChannel, TTunerBand aBand);

Description

Tune the tuner to the required digital channel number.

This is an asynchronous command and will result in a callback to MToTunerEvent with an event type of ETunerEvent. If no error has occured then the error code passed to the callback function will be KErrNone otherwise it will reflect the nature of the error.

If the session does not currently have control of the tuner, a request for control will be made. If control of the tuner is granted the MToTunerEvent will be invoked with an event type of EControlEvent. If there is no error then the error code will be KErrNone otherwise the error will be KErrAccessDenied.

Once control of the tuner has been granted, it will be retained until either a call to ReleaseTunerControl, or the session is preempted in which case there will be a callback to MToTunerEvent with an event type EControlEvent with error value KErrAccessDenied.

Parameters

TChannel aChannel The channel to tune to TTunerBand aBand The band to which aChannel belongs

IMPORT_C void StationSeek(TFrequency aStartFrequency, TTunerBand aBand, TSearchDirection aSearchDirection, TBool aCircularSeek=ETrue);

Description

Find a radio station, starting at the start frequency and searching in the direction specified (i.e. Up or down) the search is limited to the specified band.

If the session does not currently have control of the tuner, a request for control will be made. If control of the tuner is granted the MToTunerEvent will be invoked with an event type of EControlEvent. If there is no error then the error code will be KErrNone otherwise the error will be KErrAccessDenied.

Once control of the tuner has been granted, it will be retained until either a call to ReleaseTunerControl, or the session is preempted in which case there will be a callback to MToTunerEvent with an event type EControlEvent with error value KErrAccessDenied.

A callback to MToTunerEvent with an event type of ETunerEvent will occur if the Seek is successful.

Parameters

TFrequency aStartFrequency The frequency to start searching at, or 0 to start at the beginning of the stated band. TTunerBand aBand The band to which aStartFrequency belongs TSearchDirection aSearchDirection The direction to search in TBool aCircularSeek If set to ETrue the station seek will loop back to the other end of the band once the end of the band has been reached. (Defaults to ETrue) If not set reaching the end of the band without finding a station will result in a callback to MToTuneComplete with error KErrNotFound.

IMPORT_C void StationSeek(TChannel aStartChannel, TTunerBand aBand, TSearchDirection aSearchDirection, TBool aCircularScan=ETrue);

Description

Find a station, starting at the given digital channel number and searching in the direction specified (i.e. Up or down).

If the session does not currently have control of the tuner, a request for control will be made. If control of the tuner is granted the MToTunerEvent will be invoked with an event type of EControlEvent. If there is no error then the error code will be KErrNone otherwise the error will be KErrAccessDenied.

Once control of the tuner has been granted, it will be retained until either a call to ReleaseTunerControl, or the session is preempted in which case there will be a callback to MToTunerEvent with an event type EControlEvent with error value KErrAccessDenied.

A callback to MToTunerEvent with an event type of ETunerEvent will occur if the Seek is successful.

Parameters

TChannel aStartChannel The channel to start searching from TTunerBand aBand The band to which aStartChannel belongs TSearchDirection aSearchDirection The direction to search in TBool aCircularScan If set to ETrue the station seek will loop back to the other end of the channel range once the end of the channel range has been reached. (Defaults to ETrue) If not set reaching the end of the band without finding a station will result in a callback to MToTuneComplete with error KErrNotFound.

IMPORT_C void CancelRetune();

Description

Cancels an ongoing retune operation, as initiated by a call to Tune or StationSeek. The usual callback will not occur if this has been called.

Has not affect if no tune or seek operation is ongoing.

IMPORT_C TInt RequestTunerControl();

Description

Makes a synchronous request for control of the tuner. If this method returns KErrNone, control of the tuner has been granted. Control of the tuner is kept until it is explicitly released using ReleaseTunerControl, or it is revoked in which case a callback to MToTunerEvent with an event type of EControlEvent and an error of KErrAccessDenied will occur.

If this method returns with KErrAccessDenied, a request to recieve a notification when control could be granted can be made using NotifyTunerControl.

Note that methods that require control of the tuner (such as Tune) will make a request for control themselves if control has not already been granted.

Return value

TInt A standard system error code. If control was granted, KErrNone, and if control was denied KErrAccessDenied.

IMPORT_C TInt NotifyTunerControl();

Description

Makes an asyncronous request for control of the tuner. This method should be called after an control of the tuner has been denied to receive a notification when control of the tuner can be granted. A callback to MToTunerEvent with an event type of EControlEvent and an error of KErrNone will occur in this event.

Return value

TInt

IMPORT_C void ReleaseTunerControl();

Description

Release control of the tuner, allowing other clients to tune it. Change notifications may still be received. A request for control of the tuner can be made again by calling RequestTunerControl, or any methods that require control of the tuner.

IMPORT_C void Close();

Description

Release the tuner. Any ongoing playing or recording activity will be stopped, control of the tuner will be released, and the hardware will be powered down if no other clients need it.

IMPORT_C TInt GetFrequency(TFrequency &aFrequency, TTunerBand &aBand) const;

Description

Retrieve the current frequency that the tuner is tuned to

Parameters

TFrequency &aFrequency The variable to set to the current frequency, -1 if channels are in use TTunerBand &aBand The variable used to set the current band.

Return value

TInt A standard system error code

IMPORT_C TInt GetChannel(TChannel &aChannel, TTunerBand &aBand) const;

Description

Retrieve the current digital channel number that the tuner is tuned to

Parameters

TChannel &aChannel The variable to set to the current channel, -1 if frequencies are in use TTunerBand &aBand The variable to set to the current band

Return value

TInt A standard system error code

IMPORT_C TInt GetSignalStrength(TInt &aSignalStrength) const;

Description

Retrieve the signal strenth of the currently tuned signal

Parameters

TInt &aSignalStrength Variable into which the signal strength will be written.

Return value

TInt A standard system error code

IMPORT_C TInt GetMaxSignalStrength(TInt &aMaxSignalStrength) const;

Description

Get the maximum possible signal strength of a tuned signal.

Parameters

TInt &aMaxSignalStrength A variable that will have the maximun signal strength written to.

Return value

TInt A standard system error code

IMPORT_C TInt NotifySignalStrength(MMMSignalStrengthObserver &aObserver);

Description

Request notifications when the signal strength changes. Due to the potentially short intervals at which the signal strength may change at, notifications will only be sent when a relatively large change occurs. This should allow a visual display of signal strength to be maintained fairly accurately.

The first signal strength notification will be sent immediately after this request.

Parameters

MMMSignalStrengthObserver &aObserver The object which will receive notifications of signal strength changes.

Return value

TInt A standard system error code

IMPORT_C void CancelNotifySignalStrength();

Description

Cancel an outstanding NotifySignalStrength request.

IMPORT_C TInt IsStereoSignal(TBool &aStereo);

Description

Find out if the current signal is being received in stereo or not.

Parameters

TBool &aStereo On return, will be ETrue if and only if a stereo signal is currently being received.

Return value

TInt A standard system error code

IMPORT_C TInt NotifyStereoChange(MMMTunerStereoObserver &aObserver);

Description

Request notifications when stereo reception is lost/restored.

Parameters

MMMTunerStereoObserver &aObserver The object requiring notification when a stereo signal is lost or restored. The first notification will occur immediately.

Return value

TInt A standard system error code

IMPORT_C void CancelNotifyStereoChange();

Description

Cancels a stereo change notification request.

IMPORT_C TInt ForceMonoReception(TBool aMono);

Description

Indicates whether the reception should be forced into monophonic mode.

Parameters

TBool aMono If ETrue, all reception will be in mono mode even if a stereo signal is available. If EFalse, a stereo signal will be received when possible.

Return value

TInt A standard system error code.

IMPORT_C TInt GetForcedMonoReception(TBool &aMono) const;

Description

Find out whether reception is forced into monophonic mode or not.

Parameters

TBool &aMono This will be set to ETrue if all reception is forced to be mono. If this is EFalse, this does not imply that stereo reception is currently available.

Return value

TInt A standard system error code.

IMPORT_C TInt SetSquelch(TBool aEnabled);

Description

Sets the current squleching (muting in frequencies without reception) setting.

Parameters

TBool aEnabled ETrue to enable squelching, EFalse to disable it.

Return value

TInt KErrNone if successful, else a system wide error code.

IMPORT_C TInt GetSquelch(TBool &aEnabled) const;

Description

Gets the current squleching (muting in frequencies without reception) setting.

Parameters

TBool &aEnabled This will be set to ETrue if squelching is enabled, EFalse otherwise.

Return value

TInt KErrNone if successful, else a system wide error code.

IMPORT_C TInt GetFrequencyBandRange(TTunerBand aBand, TFrequency &aBottomFrequency, TFrequency &aTopFrequency);

Description

Get the frequency range (in Hertz) of the specified band. This function should be used to enquire the frequency range of the bands that GetCapabilities reports as supported.

Parameters

TTunerBand aBand The band to query TFrequency &aBottomFrequency The variable to set to the lowest frequency allowed TFrequency &aTopFrequency The variable to set to the highest frequency allowed

Return value

TInt A standard system error code

IMPORT_C TInt GetChannelRange(TTunerBand aBand, TChannel &aBottomChannel, TChannel &aTopChannel) const;

Description

Get the channel range available for a given band

Parameters

TTunerBand aBand The band for which the channel range is being requested. This must be a band which used channels. TChannel &aBottomChannel The variable to set to the lowest channel allowed TChannel &aTopChannel The variable to set to the highest channel allowed

Return value

TInt A standard system error code

IMPORT_C TInt NotifyChange(MMMTunerChangeObserver &aObserver);

Description

Request to be notified when the tuned frequency or channel changes, or when the tuner changes state (e.g. starts playing or recording)

Parameters

MMMTunerChangeObserver &aObserver The object wishing to receive tuning change events

Return value

TInt A standard system error code

IMPORT_C void CancelNotifyChange();

Description

Cancel request to be notified when the tuned frequency or channel changes

IMPORT_C TInt CustomCommandSync(TInt aFunction, const TIpcArgs &aArgs);

Description

Send a synchronous custom command to the tuner.

Parameters

TInt aFunction The function number to indicate which function is to be called on the interface defined by the first IPC argument const TIpcArgs &aArgs The IPC arguments to send to the tuner. The first of these arguments must be the UID of the interface within the tuner to which the command is destined, represented as an integer. Failure to set the first argument properly will result in the command completing with KErrNotSupported at best, but possibly the client being panicked.

Return value

TInt A standard system error code

IMPORT_C void CustomCommandAsync(TInt aFunction, const TIpcArgs &aArgs, TRequestStatus &aStatus);

Description

Send an asynchronous custom command to the tuner.

Parameters

TInt aFunction The function number to indicate which function is to be called on the interface defined by the first IPC argument const TIpcArgs &aArgs The IPC arguments to send to the tuner. The first of these arguments must be the UID of the interface within the tuner to which the command is destined, represented as an integer. Failure to set the first argument properly will result in the command completing with KErrNotSupported at best, but possibly the client being panicked. TRequestStatus &aStatus The TRequestStatus of an active object. This will contain the result of the request on completion. The exact range of result values is dependent on the interface.

IMPORT_C TAny *CustomInterface(TUid aInterface);

Description

Requests a custom interface from the tuner plugin

Parameters

TUid aInterface a unique identifier identifying the requested interace

Return value

TAny * A pointer to a custom interface or NULL to signify failure

TTunerBand

Description

Tuner Band bit flags - may be extended in future

ETunerNoBand No band selected ETunerBandLw Long Wave - uses frequencies ETunerBandAm Amplitude Modulation or Medium Wave - uses frequencies ETunerBandFm Frequency Modulation, European and American band - uses frequencies ETunerBandJapaneseFm Frequency Modulation, Japanese band - uses frequencies ETunerBandDab Digital Audio Broadcasting - uses channels ETunerBandDvb Digital Video Broadcasting

TSearchDirection

Description

Search direction enumeration

ESearchDirectionUp Search for stations upwards - i.e. by increasing frequency ESearchDirectionDown Search for stations downwards - i.e. by decreasing frequency

TTunerAccessPriority

Description

The Tuner Access Priority enables clients to correctly identify their needs when it comes to accessing the tuner. A process must have the MultimediaDD capability to use priorities greater than ETunerAccessPriorityNormal.

ETunerAccessPriorityBackground Radio accessible when device is idle ETunerAccessPriorityNormal Ordinary application priority ETunerAccessPriorityAlarm Radio is to be used as an alarm sound ETunerAccessPrioritySystem System use only

TTunerState

Description

Bitmasks to indicate what state the tuner is in.

ETunerStateActive Tuner is active, and can therefore report frequency etc. If this bit is not set, none of the others should be set. ETunerStatePlaying The tuner is playing sound. ETunerStateRecording The tuner is currently recording. ETunerStateRetuning The tuner is currently retuning or searching for a new station.