diff -r e5618cc85d74 -r 6c158198356e javauis/amms_akn/src_tuner/native/external_include/tuner.h --- a/javauis/amms_akn/src_tuner/native/external_include/tuner.h Thu Jul 15 18:31:06 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,2535 +0,0 @@ -/* -* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). -* All rights reserved. -* This component and the accompanying materials are made available -* under the terms of "Eclipse Public License v1.0" -* which accompanies this distribution, and is available -* at the URL "http://www.eclipse.org/legal/epl-v10.html". -* -* Initial Contributors: -* Nokia Corporation - initial contribution. -* -* Contributors: -* -* Description: Header file for Tuner component. -* -*/ - - -#ifndef TUNER_H -#define TUNER_H - -#include -#include -#include -#include -#include -#include -#include -#include -class RRadioSession; - -/** -@file -@publishedAll -@prototype -*/ -/** -The Tuner Capabilities structure defines the capabilities of the tuner -on the device, as retrieved using the function GetCapabilities. -*/ -class TTunerCapabilities -{ -public: - inline TTunerCapabilities(); - inline TTunerCapabilities(TUint32 aTunerBands, TUint32 aAdditionalFunctions); -public: - /** - Bitfield (as defined by CMMTunerUtility::TTunerBand) with the bits of the - supported bands set - */ - TUint32 iTunerBands; - - /** Tuner Function bit flags - may be extended in future */ - enum TTunerFunctions - { - /** Recording of Tuner Audio is possible */ - ETunerFunctionRecording = 0x01, - /** Tuner can record and play back simultaneously */ - ETunerFunctionSimultaneousPlayAndRecord = 0x02, - /** The tuner requires an external antenna (e.g. a headset) to function */ - ETunerFunctionRequiresAntenna = 0x04, - /** CMMRdsTunerUtility supported */ - ETunerFunctionRds = 0x08, - /** The tuner can be used when the device is in flight mode */ - ETunerFunctionAvailableInFlightMode = 0x10 - }; - - /** Bitfield (as defined by ETunerFunctions) with the bits of the supported functions set */ - TUint32 iAdditionalFunctions; -}; - -/** -Class representing a frequency. -*/ -class TFrequency -{ -public: - inline TFrequency(); - explicit inline TFrequency(TInt aFrequency); - inline TInt operator==(const TFrequency& aFrequency) const; - inline TInt operator!=(const TFrequency& aFrequency) const; - inline TInt operator> (const TFrequency& aFrequency) const; - inline TInt operator>=(const TFrequency& aFrequency) const; - inline TInt operator< (const TFrequency& aFrequency) const; - inline TInt operator<=(const TFrequency& aFrequency) const; -public: - /** - The Frequency, in Hertz. A TInt is at least 32 bits, giving a maximum frequency - of at least 2.4GHz (i.e. 0x7fffffff Hz) - */ - TInt iFrequency; -}; - - -class MMMTunerObserver; -class MMMTunerChangeObserver; -class MMMTunerStereoObserver; -class MMMSignalStrengthObserver; -class MMMTunerAudioPlayerObserver; -class MMMTunerAudioRecorderObserver; -class CMMTunerAudioPlayerUtility; -class CMMTunerAudioRecorderUtility; -class CMMTunerScannerUtility; -class CMMRdsTunerUtility; - -/** -The MMF Tuner API is present to allow clients to control -the tuner hardware present on a device. -*/ -class CMMTunerUtility : public CBase -{ - friend class CMMTunerAudioPlayerUtility; - friend class CMMTunerAudioRecorderUtility; - friend class CMMTunerScannerUtility; - friend class CMMRdsTunerUtility; -public: - /** Tuner Band bit flags - may be extended in future */ - enum TTunerBand - { - ETunerNoBand = 0x00, - /** Long Wave - uses frequencies */ - ETunerBandLw = 0x01, - /** Amplitude Modulation or Medium Wave - uses frequencies */ - ETunerBandAm = 0x02, - /** Frequency Modulation, European and American band - uses frequencies */ - ETunerBandFm = 0x04, - /** Frequency Modulation, Japanese band - uses frequencies */ - ETunerBandJapaneseFm = 0x08, - /** Digital Audio Broadcasting - uses channels */ - ETunerBandDab = 0x10, - /** Digital Video Broadcasting */ - ETunerBandDvb = 0x20 - }; - /** - Search direction enumeration - */ - enum TSearchDirection - { - /** Search for stations upwards - i.e. by increasing frequency */ - ESearchDirectionUp = 1, - /** Search for stations downwards - i.e. by decreasing frequency */ - ESearchDirectionDown - }; - /** - 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. - */ - enum TTunerAccessPriority - { - /** Radio accessible when device is idle */ - ETunerAccessPriorityBackground = -100, - /** Ordinary application priority */ - ETunerAccessPriorityNormal = 0, - /** Radio is to be used as an alarm sound */ - ETunerAccessPriorityAlarm = 75, - /** System use only */ - ETunerAccessPrioritySystem = 100 - }; - /** - Bitmasks to indicate what state the tuner is in. - */ - enum TTunerState - { - /** - Tuner is active, and can therefore report frequency etc. If this bit is - not set, none of the others should be set. - */ - ETunerStateActive = 0x01, - /** The tuner is playing sound. */ - ETunerStatePlaying = 0x02, - /** The tuner is currently recording. */ - ETunerStateRecording = 0x04, - /** The tuner is currently retuning or searching for a new station. */ - ETunerStateRetuning = 0x08, - }; -public: - - /** - 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. - - @param aObserver The observer object for receiving async completion callbacks - @param aTunerIndex An index from 0 to TunersAvailable() - 1 specifying the tuner - device to use. - @param aAccessPriority Tuner access priority value - @leave KErrNoMemory Out of memory - @leave KErrNotFound The specified tuner or tuner controller is not present - @return A pointer and ownership of the fully constructed CMMTunerUtility object - */ - IMPORT_C static CMMTunerUtility* NewL(MMMTunerObserver& aObserver, - TTunerBand aBand, - TInt aTunerIndex, - CMMTunerUtility::TTunerAccessPriority aAccessPriority = ETunerAccessPriorityNormal); - - IMPORT_C virtual ~CMMTunerUtility(); - - - - /** - 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. - - The platform security capability is MultimediaDD and a client with this capability - is allowed to set the priority in preference to a client with a lower capability. - - @param aAccessPriority The new priority to use. - @capability MultimediaDD - @return A standard system error code. - */ - IMPORT_C TInt SetPriority(TTunerAccessPriority aAccessPriority); - - /** - Get the current tuner access priority of this client. - - @param aAccessPriority A variable to which the current priority will be written. - @return A standard system error code. - */ - IMPORT_C TInt GetPriority(TTunerAccessPriority& aAccessPriority) const; - - - /** - Get the current state of the tuner. - - @param aState A variable to set with the current state. Bits set according to - TTunerState. - @return A standard system error code. - */ - IMPORT_C TInt GetState(TUint32& aState) const; - - /** - 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. - - @param aAttached When this function returns, this will contain ETrue if and only - if an external antenna is attached. - @return A standard system error code. - */ - IMPORT_C TInt IsAntennaAttached(TBool& aAttached); - - /** - 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. - - @param aFlightMode On return, this will have been set to ETrue if and only if - the device is in flight mode. - @return A standard system error code. - */ - IMPORT_C TInt GetFlightMode(TBool& aFlightMode) const; - - /** - Tune the tuner to the required frequency specified in Hertz. This is an asynchronous - command and will result in a callback to MToTuneComplete or MToTunerError. - - 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, a callback to MToTunerControlGranted - will occur. If not, there will be a callback to MtoTunerError with error value - 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 MToTunerError with error value KErrAccessDenied. - - @param aFrequency The frequency to tune to - @param aBand The band to which aFrequency belongs - */ - IMPORT_C void Tune(TFrequency aFrequency); - - /** - 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, a callback to - MToTunerControlGranted will occur. If not, there will be a callback to MToTunerError - with error value 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 MToTunerError with error value KErrAccessDenied. - - A callback to MToTuneComplete will occur if the Seek is successful. - - @param aBand The band - @param aSearchDirect The direction to search in - @param 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(TSearchDirection aSearchDirection); - - /** - 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 void CancelRetune(); - - /** - 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 explically released using ReleaseTunerControl, or it is revoked - in which case a callback to MToTunerError with an error of KErrAccessDenied - will occur. - - If this method returns with KErrAccessDenied, a request to recieve a - notifiaction 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 A standard system error code. If control was granted, KErrNone, and if - control was denied KErrAccessDenied. - */ - IMPORT_C TInt RequestTunerControl(); - - /** - 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 MToTunerControlGranted - will occur in this event. - */ - IMPORT_C TInt NotifyTunerControl(); - - /** - 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 ReleaseTunerControl(); - - /** - 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 void Close(); - - /** - Retrieve the current frequency that the tuner is tuned to - - @param aFrequency The variable to set to the current frequency, - -1 if channels are in use - @param aBand The variable used to set the current band. - @return A standard system error code - */ - IMPORT_C TInt GetFrequency(TFrequency& aFrequency) const; - - /** - Retrieve the signal strenth of the currently tuned signal - - @param aSignalStrength Variable into which the signal strength will be written. - @return A standard system error code - */ - IMPORT_C TInt GetSignalStrength(TInt& aSignalStrength) const; - - /** - Get the maximum possible signal strength of a tuned signal. - - @param aMaxSignalStrength A variable that will have the maximun signal strength - written to. - @return A standard system error code - */ - IMPORT_C TInt GetMaxSignalStrength(TInt& aMaxSignalStrength) const; - - /** - 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 occurrs. 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. - - @param aObserver The object which will receive notifications of signal strength - changes. - @return A standard system error code - */ - IMPORT_C TInt NotifySignalStrength(MMMSignalStrengthObserver& aObserver); - - /** - Cancel an outstanding NotifySignalStrength request. - */ - IMPORT_C void CancelNotifySignalStrength(); - - /** - Find out if the current signal is being received in stereo or not. - - @param aStereo On return, will be ETrue if and only if a stereo signal is - currently being received. - */ - IMPORT_C TInt IsStereoSignal(TBool& aStereo); - - /** - Request notifications when stereo reception is lost/restored. - - @param aObserver The object requiring notification when a stereo signal is lost - or restored. The first notification will occur immediately. - @return A standard system error code - */ - IMPORT_C TInt NotifyStereoChange(MMMTunerStereoObserver& aObserver); - - /** - Cancels a stereo change notification request. - */ - IMPORT_C void CancelNotifyStereoChange(); - - /** - Indicates whether the reception should be forced into monophonic mode. - - @param 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 A standard system error code. - */ - IMPORT_C TInt ForceMonoReception(TBool aMono); - - /** - Find out whether reception is forced into monophonic mode or not. - - @param 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 A standard system error code. - */ - IMPORT_C TInt GetForcedMonoReception(TBool& aMono) const; - - /** - Sets the current squleching (muting in frequencies without reception) setting. - - @param aEnabled ETrue to enable squelching, EFalse to disable it. - @return KErrNone if successful, else a system wide error code. - */ - IMPORT_C TInt SetSquelch(TBool aEnabled); - - /** - Gets the current squleching (muting in frequencies without reception) setting. - - @param aEnabled This will be set to ETrue if squelching is enabled, EFalse otherwise. - @return KErrNone if successful, else a system wide error code. - */ - IMPORT_C TInt GetSquelch(TBool& aEnabled) const; - - /** - Get the capabilities of the tuner on the device - - @param aCaps The capabilities object to fill - @return A standard system error code - */ - IMPORT_C TInt GetCapabilities(TTunerCapabilities& aCaps) const; - - /** - 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. - - @param aBand The band to query - @param aBottomFrequency The variable to set to the lowest frequency allowed - @param aTopFrequency The variable to set to the highest frequency allowed - @return A standard system error code - */ - IMPORT_C TInt GetFrequencyBandRange(TFrequency& aBottomFrequency, TFrequency& aTopFrequency); - - /** - Request to be notified when the tuned frequency or channel changes, or when the - tuner changes state (e.g. starts playing or recording) - - @param aObserver The object wishing to receive tuning change events - @return A standard system error code - */ - IMPORT_C TInt NotifyChange(MMMTunerChangeObserver& aObserver); - - /** - Cancel request to be notified when the tuned frequency or channel changes - */ - IMPORT_C void CancelNotifyChange(); - - /** - Send a synchronous custom command to the tuner. - - @param aFunction The function number to indicate which function is to be called - on the interface defined by the first IPC argument - @param 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 A standard system error code - */ - IMPORT_C TInt CustomCommandSync(TInt aFunction, const TIpcArgs& aArgs); - - /** - Send an asynchronous custom command to the tuner. - - @param aFunction The function number to indicate which function is to be called - on the interface defined by the first IPC argument - @param 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. - @param 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 void CustomCommandAsync(TInt aFunction, const TIpcArgs& aArgs, TRequestStatus& aStatus); - - /** - Get the Tuner Player Utility - - @param aAccessPriority A variable to which the current priority will be written. - @return A standard system error code. - */ - IMPORT_C CMMTunerAudioPlayerUtility* TunerPlayerUtilityL(MMMTunerAudioPlayerObserver& aObserver) ; - /** - Get the Tuner Recorder Utility - - @param aAccessPriority A variable to which the current priority will be written. - @return A standard system error code. - */ - IMPORT_C CMMTunerAudioRecorderUtility* TunerRecorderUtilityL(MMMTunerAudioRecorderObserver& aObserver) ; - - /** - Get the Tuner Scanner Utility - - @param aAccessPriority A variable to which the current priority will be written. - @return A standard system error code. - */ - IMPORT_C CMMTunerScannerUtility* TunerScannerUtilityL() ; - - /** - Get the Tuner Rds Utility - - @param aAccessPriority A variable to which the current priority will be written. - @return A standard system error code. - */ - IMPORT_C CMMRdsTunerUtility* TunerRdsUtilityL() ; - -private: - CMMTunerUtility(); -protected: - class CBody; -private: - CBody* iBody; -}; - -/** -The Tuner Observer mixin class defines asynchronous -event completion function callbacks -*/ -class MMMTunerObserver -{ -public: - /** - Tune complete event. This event is asynchronous - and is received after a call to the Tune method. - - @param aError A standard system error - */ - virtual void MToTuneComplete(TInt aError) = 0; - -}; - -/** -The Tuner Change Observer mixin class defines the interface via which -notification for changes to the tuned frequency, channel and other tuner -state can be received. A client interested in these notifications -should call the function CMMTunerUtility::NotifyChange. -*/ -class MMMTunerChangeObserver -{ -public: - /** - Called when the tuned frequency changes - - @param aOldFrequency The frequency in use before the change - @param aNewFrequency The new tuned frequency - */ - virtual void MTcoFrequencyChanged(const TFrequency& aOldFrequency, const TFrequency& aNewFrequency) = 0; - - /** - Called when the state of the tuner changes. - - @param aOldState The old state. Bits are set according to TTunerState. - @param aNewState The new state. Bits are set according to TTunerState. - */ - virtual void MTcoStateChanged(const TUint32& aOldState, const TUint32& aNewState) = 0; - - /** - This function is called when an external antenna is detached from the device. - This does not necessarily indicate that the tuner can no longer be used; the - capabilities of the tuner indicate if the external antenna is required in order - to use the tuner. - */ - virtual void MTcoAntennaDetached() = 0; - - /** - This function is called when an external antenna is attached to the device. If - the antenna is required to use the tuner, this indicates that the tuner can be - used again. - */ - virtual void MTcoAntennaAttached() = 0; - - /** - This function is called when the device enters or leaves flight mode. If the tuner - cannot be used in flight mode when the device enters this mode, this indicates - that the tuner can no longer be used; the capabilities of the tuner indicate if - it can be used in flight mode or not. - - @param aFlightMode ETrue if the device has just entered flight mode, EFalse if - flight mode has just been left. - */ - virtual void FlightModeChanged(TBool aFlightMode) = 0; -}; - -/** -The stereo observer mixin class defines the interface by which clients can be -notified when a stereo signal is received/lost. An interested client should call -the function CMMTunerUtility::NotifyStereoChange. -*/ -class MMMTunerStereoObserver -{ -public: - /** - Called when stereo reception is lost/restored. - - @param aStereo If true, indicates that stereo reception has just been restored. - If false, indicates that stereo reception has just been lost. - */ - virtual void MTsoStereoReceptionChanged(TBool aStereo) = 0; - - /** - Called when a client enables/disabled forced mono reception. - - @param aForcedMono ETrue if reception is forced to be mono, even when a stereo - signal is available. - */ - virtual void MTsoForcedMonoChanged(TBool aForcedMono) = 0; -}; - -/** -This mixin class should be derived from by clients wishing to receive -notifications when the signal strength changes. Such a client should call -function CMMTunerUtility::NotifySignalStrength. -*/ -class MMMSignalStrengthObserver -{ -public: - /** - Callback indicating that the signal strength has changed by an amount meriting - a notification. - - @param aNewSignalStrength The new signal strength. - */ - virtual void MssoSignalStrengthChanged(TInt aNewSignalStrength) = 0; -}; - - -class MMMAudioResourceNotificationCallback; - -/** -The Tuner Audio Player Utility is used to initiate and control playback of audio -from the tuner. -*/ -class CMMTunerAudioPlayerUtility : public CBase, public MCustomCommand -{ - friend class CMMTunerUtility::CBody; -public: - - IMPORT_C ~CMMTunerAudioPlayerUtility(); - - /** - Set-up the API for playing the output from tuner to the speaker asynchronously. - Calls MMMTunerAudioPlayerObserver::MTapoInitializeComplete on completion. This must be - called before Play. - - @param aPriority Sound device priority value - @param aPref Sound device priority preference value - */ - IMPORT_C void InitializeL(TInt aAudioPriority = EMdaPriorityNormal, TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality); - - /** - Start playback of the tuner output. To stop playback, call Mute, or Stop if - play will not need to be restarted. InitializeL() must have already been - called, and a callback to MTapoInitializeComplete with an error of KErrNone must - have occurred; if this is not the case, this raises a TunerAudioPlay 1 panic. - */ - IMPORT_C void Play(); - - /** - Mute or unmute playback. - - Raises a TunerAudioPlay 1 panic if the player is not properly initialized. - - @param aMute ETrue to mute the audio, EFalse to unmute it. - @return A standard system error code - */ - IMPORT_C TInt Mute(TBool aMute); - - /** - Stop playback, and release the output device for use by other clients - - Raises a TunerAudioPlay 1 panic if the player is not properly initialized. - - Playback should already be under way. - */ - IMPORT_C void Stop(); - - /** - Set the current audio priority. This priority is used to arbitrate - between multiple audio sources trying to access the audio hardware. - - @param aPriority A priority between EMdaPriorityMin and EMdaPriorityMax - @param aPref Time vs Quality priority preferences, enumerated in TMdaPriorityPreference - @return A standard system error code - */ - IMPORT_C TInt SetPriority(TInt aPriority, TMdaPriorityPreference aPref); - - /** - Get the current audio priority. This is used to arbitrate between simultaneous - accesses to the sound hardware. - - @param aPriority A priority between EMdaPriorityMin and EMdaPriorityMax to return - @param aPref Time vs Quality priority preferences to return, enumerated in TMdaPriorityPreference - @return A standard system error code - */ - IMPORT_C TInt GetPriority(TInt& aPriority, TMdaPriorityPreference& aPref) const; - - /** - Set the volume to the specified level - - Raises a TunerAudioPlay 1 panic if the player is not properly initialized. - - @param aVolume The volume level to set - @return A standard system error code - */ - IMPORT_C TInt SetVolume(TInt aVolume); - - /** - Return the current volume - - @param aVolume The variable to set to the current volume - @return A standard system error code - */ - IMPORT_C TInt GetVolume(TInt& aVolume) const; - - /** - Define a volume ramp, aRampInterval defining - the interval between valid volume settings - - Raises a TunerAudioPlay 1 panic if the player is not properly initialized. - - @param aRampInterval The time interval over which the volume - should be increased from zero to the current volume setting - @return A standard system error code - */ - IMPORT_C TInt SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampInterval); - - /** - Return the maximum volume supported - - @return The maximum volume setting permitted - */ - IMPORT_C TInt MaxVolume() const; - - /** - Set the stereo balance between left and right channels - - Raises a TunerAudioPlay 1 panic if the player is not properly initialized. - - @param aBalance The balance value to set - must be between - KMMFBalanceMaxLeft and KMMFBalanceMaxRight - @return A standard system error code - */ - IMPORT_C TInt SetBalance(TInt aBalance = KMMFBalanceCenter); - - /** - Return the current stereo balance - - @param aBalance The variable to set to the current balance - @return A standard system error code - */ - IMPORT_C TInt GetBalance(TInt& aBalance) const; - - /** - Register for audio resource notifications, in the event that the audio resource is lost due to pre-emption - by a higher priority audio client. - */ - IMPORT_C TInt RegisterAudioResourceNotification(MMMAudioResourceNotificationCallback& aCallback, TUid aNotificationEventUid, const TDesC8* aNotificationRegistrationData = NULL); - - /** - Cancel an outstanding audio resource notification. - */ - IMPORT_C void CancelRegisterAudioResourceNotification(TUid aNotificationEventId); - - /** - Returns the controller implementation information associated with the current controller, if any. - - @return The controller implementation structure associated with the controller - @leave KErrNotFound if no controller is in use. - */ - IMPORT_C const CMMFControllerImplementationInformation& ControllerImplementationInformationL(); - - /** - Send a synchronous custom command to the playback controller, if ones exists. - - @param aDestination The destination of the message, consisting of the uid of - the interface of this message - @param aFunction The function number to indicate which function is to be called - on the interface defined in the aDestination parameter - @param aDataTo1 The first chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataTo2 The second chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @return A standard system error code - */ - IMPORT_C TInt CustomCommandSync( - const TMMFMessageDestinationPckg& aDestination, - TInt aFunction, - const TDesC8& aDataTo1, - const TDesC8& aDataTo2); - - /** - Send a synchronous custom command to the playback controller, if ones exists. - - @param aDestination The destination of the message, consisting of the uid of - the interface of this message - @param aFunction The function number to indicate which function is to be called - on the interface defined in the aDestination parameter - @param aDataTo1 The first chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataTo2 The second chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataFrom The area of memory to which the controller framework - will write any data to be passed back to the client. Can't be KNullDesC8. - @return A standard system error code - */ - IMPORT_C TInt CustomCommandSync( - const TMMFMessageDestinationPckg& aDestination, - TInt aFunction, - const TDesC8& aDataTo1, - const TDesC8& aDataTo2, - TDes8& aDataFrom); - - /** - Send an asynchronous custom command to the playback controller, if ones exists. - - @param aDestination The destination of the message, consisting of the uid of - the interface of this message - @param aFunction The function number to indicate which function is to be called - on the interface defined in the aDestination parameter - @param aDataTo1 The first chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataTo2 The second chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param 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 void CustomCommandAsync( - const TMMFMessageDestinationPckg& aDestination, - TInt aFunction, - const TDesC8& aDataTo1, - const TDesC8& aDataTo2, - TRequestStatus& aStatus); - - /** - Send an asynchronous custom command to the playback controller, if ones exists. - - @param aDestination The destination of the message, consisting of the uid of - the interface of this message - @param aFunction The function number to indicate which function is to be called - on the interface defined in the aDestination parameter - @param aDataTo1 The first chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataTo2 The second chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataFrom The area of memory to which the controller framework - will write any data to be passed back to the client. Can't be KNullDesC8. - @param 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 void CustomCommandAsync( - const TMMFMessageDestinationPckg& aDestination, - TInt aFunction, - const TDesC8& aDataTo1, - const TDesC8& aDataTo2, - TDes8& aDataFrom, - TRequestStatus& aStatus); - -protected: - /** - 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. - - @param aTuner The tuner object which this utility will play the audio from. - @param aObserver The observer of the player utility to receive asychronous completion and - notifiction callbacks. - @leave KErrNoMemory Out of memory - @leave KErrNotSupported If the given tuner doesn't support audio playback. - @return A new tuner audio player utility. - */ - static CMMTunerAudioPlayerUtility* NewL(CMMTunerUtility& aTuner, RRadioSession& aRadioSession, MMMTunerAudioPlayerObserver& aObserver); - -private: - CMMTunerAudioPlayerUtility(); -private: - class CBody; - CBody* iBody; -}; - -class MMMTunerAudioPlayerObserver -{ -public: - /** - The TEvent enumeration is used to indicate which type of event is being sent to the client. - Each event will be associated with an error code and potentially some addition information, - and will be passed to the client via method MTapoPlayEvent(). - */ - enum TEventType - { - /** An event relating to the tuner itself. Any error other than KErrNone associated - with this event type may indicate that the tuner cannot be used anymore. - - No additional information is associated with this type of event. */ - ETunerEvent, - /** - An event relating to audio playback. - - No additional information is associated with this type of event. - */ - EAudioEvent - }; -public: - /** - Initialize complete event. This event is asynchronous and is received after - a call to CMMTunerAudioPlayerUtility::InitializeL(). - - @param aError A standard system error - */ - virtual void MTapoInitializeComplete(TInt aError) = 0; - - /** - Passes an asychronous event to the tuner client. - - @param aEvent The type of event. See enumeration MMMTunerAudioPlayerObserver::TEventType - for more information about when the event types mean. - @param aError An error code associated with the event. - @param aAdditionalInfo Any additional information associated with the event, or NULL if - no such additional information exists. - */ - virtual void MTapoPlayEvent(TEventType aEvent, TInt aError, TAny* aAdditionalInfo) = 0; -}; - -/** -This class is used to perform recording of audio from the tuner. Many of the methods -in this class have identical functionality to similarly names functions in class -CMdaAudioRecorderUtility. -*/ -class CMMTunerAudioRecorderUtility : public CBase -{ - friend class CMMTunerUtility::CBody; -public: - - IMPORT_C ~CMMTunerAudioRecorderUtility(); - - /** - Initialize for recording from the tuner to the specified file - asynchronously. Calls MMMTunerAudioRecorderObserver::MTaroInitializeComplete on completion - - @param aRecordFilename The name of the file to create, if necessary, and record to - @param "aDestinationDataType" Data type for recording - @param "aControllerUid" The Uid of the controller to use for recording - @param "aDestinationFormatUid" Uid of record format - @param aPriority Sound device priority value - @param aPref Sound device priority preference value - */ - IMPORT_C void InitializeL(const TDesC& aRecordFilename, - TFourCC aDestinationDataType = KFourCCNULL, - TUid aControllerUid=KNullUid, - TUid aDestinationFormatUid=KNullUid, - TInt aAudioPriority = EMdaPriorityNormal, - TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality); - - /** - Initialize for recording from the tuner to the specified descriptor - asynchronously. Calls MMMTunerAudioRecorderObserver::MTaroInitializeComplete on completion - - @param aRecordDescriptor The descriptor to record to - @param "aDestinationDataType" Data type for recording - @param "aControllerUid" The Uid of the controller to use for recording - @param "aDestinationFormatUid" Uid of record format - @param aPriority Sound device priority value - @param aPref Sound device priority preference value - */ - IMPORT_C void InitializeL(TDes8& aRecordDescriptor, - TFourCC aDestinationDataType = KFourCCNULL, - TUid aControllerUid=KNullUid, - TUid aDestinationFormatUid=KNullUid, - TInt aAudioPriority = EMdaPriorityNormal, - TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality); - - /** - Return a list of the supported data types for the record destination - @param "aSupportedDataTypes" list of four character codes, representing supported data - encodings for the record destination. - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C void GetSupportedDestinationDataTypesL(RArray& aSupportedDataTypes) const; - - /** - Set the data type of the destination audio clip - @param "aDataType" four character code, representing the encoding of the destination audio clip - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C void SetDestinationDataTypeL(TFourCC aDataType); - - /** - Return the data type of the destination audio clip - @returns four character code, representing the encoding of the destination audio clip - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C TFourCC DestinationDataTypeL() const; - - /** - Set the bit rate for recording - @param "aBitRate" destination bit rate in bits/second - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C void SetDestinationBitRateL(TUint aBitRate); - - /** - Return the recording bit rate - @returns destination bit rate in bits/second - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C TUint DestinationBitRateL() const; - - /** - Return a list of the supported bit rates for recording - @param "aSupportedBitRates" List of bit rates supported for the record - destination - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C void GetSupportedBitRatesL(RArray& aSupportedBitRates) const; - - /** - Set the sample rate for the record destination - @param "aSampleRate" The sample rate of the record destination - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C void SetDestinationSampleRateL(TUint aSampleRate); - - /** - Return the sample rate of the record destination - @returns The sample rate of the record destination - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C TUint DestinationSampleRateL() const; - - /** - Get a list of supported recording sample rates. - @param "aSupportedSampleRates" List of the sample rates that are supported for - recording - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C void GetSupportedSampleRatesL(RArray& aSupportedSampleRates) const; - - /** - Set the format of the audio clip. This can only be done if the audio clip does not - exist - - @param "aFormatUid" Uid of the audio clip format - @leaves KErrAlreadyExists if the clip already exists and the format is different - from the existing format, or can leave with one of the system-wide error codes - */ - IMPORT_C void SetDestinationFormatL(TUid aFormatUid); - - /** - Return the format of the audio clip - @returns Uid of the audio clip format - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C TUid DestinationFormatL() const; - - /** - Set the number of channels for the recorded audio clip - @param "aNumberOfChannels" The number of channels to record - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C void SetDestinationNumberOfChannelsL(TUint aNumberOfChannels); - - /** - Return the number of channels in audio clip - @returns number of channels supported by audio clip - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C TUint DestinationNumberOfChannelsL() const; - - /** - Return a list of the supported number of channels for recording - @param "aSupportedNumChannels" List of the number of channels supported for - recording - @leaves Can leave with one of the system-wide error codes - */ - IMPORT_C void GetSupportedNumberOfChannelsL(RArray& aSupportedNumChannels) const; - - /** Start recording of the tuner output */ - IMPORT_C void RecordL(); - - /** - Pause recording. Recording can be resumed with another call to Record. - - @return A standard system error code - */ - IMPORT_C TInt PauseRecord(); - - /** - Stop recording, and release the output device for use by other clients - - Recording should already be under way. - */ - IMPORT_C void Stop(); - - /** - Stop recording, and release the output device for use by other clients - - Recording should already be under way. - */ - IMPORT_C void Close(); - - /** - Return the maximum value for the gain - - @return The maximum gain. For devices where automatic gain control is used, this value may be zero. - */ - IMPORT_C TInt MaxGain() const; - - /** - Sets the gain for the audio device to a specified value. - - @param aGain The gain setting. This can be any value from zero to the value returned by a call to - MaxGain(). A value which is less than zero is set to zero. A value which is greater than - MaxGain() is set to MaxGain(). - */ - IMPORT_C void SetGain(TInt aGain); - - /** - Sets the current recording balance setting between the left and right stereo channels - - The balance can be changed before or during recording and is effective immediately. - - @param aBalance The balance value to set. Any value between KMMFBalanceMaxLeft and - KMMFBalanceMaxRight, the default value being KMMFBalanceCenter. - @return An error code indicating if the call was successful. KErrNone on success, - otherwise another of the system-wide error codes. - */ - IMPORT_C TInt SetRecordBalance(TInt aBalance = KMMFBalanceCenter); - - /** - Returns the current recording balance setting between the left and right stereo channels. - - @param aBalance On return, contains the current recording balance between KMMFBalanceMaxLeft - and KMMFBalanceMaxRight. - @return An error code indicating if the call was successful. KErrNone on success, otherwise - another of the system-wide error codes. - */ - IMPORT_C TInt GetRecordBalance(TInt& aBalance) const; - - /** - Set the current audio priority. This priority is used to arbitrate - between multiple audio sources trying to access the audio hardware. - - @param aPriority A priority between EMdaPriorityMin and EMdaPriorityMax - @param aPref Time vs Quality priority preferences, enumerated in TMdaPriorityPreference - @return A standard system error code - */ - IMPORT_C TInt SetPriority(TInt aPriority, TMdaPriorityPreference aPref); - - /** - Get the current audio priority. This is used to arbitrate between simultaneous - accesses to the sound hardware. - - @param aPriority A priority between EMdaPriorityMin and EMdaPriorityMax to return - @param aPref Time vs Quality priority preferences to return, enumerated in TMdaPriorityPreference - @return A standard system error code - */ - IMPORT_C TInt GetPriority(TInt& aPriority, TMdaPriorityPreference& aPref) const; - - /** - Register for audio resource notifications, in the event that the audio resource is lost due to pre-emption - by a higher priority audio client. - */ - IMPORT_C TInt RegisterAudioResourceNotification(MMMAudioResourceNotificationCallback& aCallback, TUid aNotificationEventUid, const TDesC8* aNotificationRegistrationData = NULL); - - /** - Cancel an outstanding audio resource notification. - */ - IMPORT_C void CancelRegisterAudioResourceNotification(TUid aNotificationEventId); - - - /** - Sets the maximum size for a file that is being recorded. - - When this limit is reached, MMF stops recording and notifies the client application. Notification is caused - by MMdaObjectStateChangeObserver::MoscoStateChangeEvent() with the error code KErrEof. - - This function is provided so that applications such as recorders can limit the amount of file storage/memory - that should be allocated. - - @param aMaxWriteLength - The maximum file size in kilobytes. If the default value is used, there is no maximum file size. - - */ - IMPORT_C void SetMaxWriteLength(TInt aMaxWriteLength = KMdaClipLocationMaxWriteLengthNone); - - /** - Returns the recording time available for the selected file or descriptor and encoding format. - */ - IMPORT_C const TTimeIntervalMicroSeconds& RecordTimeAvailable(); - - /** - Returns the duration of the audio sample data. - */ - IMPORT_C const TTimeIntervalMicroSeconds& Duration(); - - /** - Return the controller implementation information structure of the current controller - - @leave KErrNoMemory Out of memory - @return A reference to the current controller information - */ - IMPORT_C const CMMFControllerImplementationInformation& ControllerImplementationInformationL(); - - /* - Returns the number of meta data entries associated with this clip. - @return Number of metadata entries - */ - IMPORT_C TInt GetNumberOfMetaDataEntries(TInt& aNumEntries); - - /* - Returns the specified meta data entry from the current audio clip. - @return Metadata entry - */ - IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aMetaDataIndex); - - /* - Adds a meta data entry to the audio clip. - */ - IMPORT_C void AddMetaDataEntryL(CMMFMetaDataEntry& aMetaDataEntry); - - /* - Removes a specified meta data entry from the audio clip - @return An error code indicating if the call was successful - */ - IMPORT_C TInt RemoveMetaDataEntry(TInt aMetaDataIndex); - - /* - Replaces the specified meta data entry with a new entry - */ - IMPORT_C void ReplaceMetaDataEntryL(TInt aMetaDataIndex, CMMFMetaDataEntry& aMetaDataEntry); - - - /** - Send a synchronous custom command to the recording controller - - @param aDestination The destination of the message, consisting of the uid of - the interface of this message - @param aFunction The function number to indicate which function is to be called - on the interface defined in the aDestination parameter - @param aDataTo1 The first chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataTo2 The second chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @return A standard system error code - */ - IMPORT_C TInt CustomCommandSync( - const TMMFMessageDestinationPckg& aDestination, - TInt aFunction, - const TDesC8& aDataTo1, - const TDesC8& aDataTo2); - - /** - Send a synchronous custom command to the recording controller - - @param aDestination The destination of the message, consisting of the uid of - the interface of this message - @param aFunction The function number to indicate which function is to be called - on the interface defined in the aDestination parameter - @param aDataTo1 The first chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataTo2 The second chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataFrom The area of memory to which the controller framework - will write any data to be passed back to the client. Can't be KNullDesC8. - @return A standard system error code - */ - IMPORT_C TInt CustomCommandSync( - const TMMFMessageDestinationPckg& aDestination, - TInt aFunction, - const TDesC8& aDataTo1, - const TDesC8& aDataTo2, - TDes8& aDataFrom); - - /** - Send an asynchronous custom command to the recording controller - - @param aDestination The destination of the message, consisting of the uid of - the interface of this message - @param aFunction The function number to indicate which function is to be called - on the interface defined in the aDestination parameter - @param aDataTo1 The first chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataTo2 The second chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param 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. - @return A standard system error code - */ - IMPORT_C void CustomCommandAsync( - const TMMFMessageDestinationPckg& aDestination, - TInt aFunction, - const TDesC8& aDataTo1, - const TDesC8& aDataTo2, - TRequestStatus& aStatus); - - /** - Send an asynchronous custom command to the recording controller - - @param aDestination The destination of the message, consisting of the uid of - the interface of this message - @param aFunction The function number to indicate which function is to be called - on the interface defined in the aDestination parameter - @param aDataTo1 The first chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataTo2 The second chunk of data to be copied to the controller - framework. The exact contents of the data are dependent on the - interface being called. Can be KNullDesC8. - @param aDataFrom The area of memory to which the controller framework - will write any data to be passed back to the client. Can't be KNullDesC8. - @param 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. - @return A standard system error code - */ - IMPORT_C void CustomCommandAsync( - const TMMFMessageDestinationPckg& aDestination, - TInt aFunction, - const TDesC8& aDataTo1, - const TDesC8& aDataTo2, - TDes8& aDataFrom, - TRequestStatus& aStatus); - -protected: - /** - Create a new 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. - */ - static CMMTunerAudioRecorderUtility* NewL(CMMTunerUtility& aTuner, MMMTunerAudioRecorderObserver& aObserver); - -private: - CMMTunerAudioRecorderUtility(); -private: - class CBody; - CBody* iBody; - -}; - -class MMMTunerAudioRecorderObserver -{ -public: - /** - The TEvent enumeration is used to indicate which type of event is being sent to the client. - Each event will be associated with an error code and potentially some addition information, - and will be passed to the client via method MTaroRecordEvent(). - */ - enum TEventType - { - /** An event relating to the tuner itself. Any error other than KErrNone associated - with this event type may indicate that the tuner cannot be used anymore. - - No additional information is associated with this type of event. */ - ETunerEvent, - /** - An event relating to audio recording. - - No additional information is associated with this type of event. - */ - EAudioEvent - }; -public: - /** - Initialize complete event. This event is asynchronous and is received after - a call to CMMTunerAudioRecorderUtility::InitializeL. - - @param aError A standard system error - */ - virtual void MTaroInitializeComplete(TInt aError) = 0; - - /** - Passes an asychronous event to the tuner client. - - @param aEvent The type of event. See enumeration MMMTunerAudioRecorderObserver::TEventType - for more information about when the event types mean. - @param aError An error code associated with the event. - @param aAdditionalInfo Any additional information associated with the event, or NULL if - no such additional information exists. - */ - virtual void MTaroRecordEvent(TEventType aEvent, TInt aError, TAny* aAdditionalInfo) = 0; -}; - -/** -This class augments CMMTunerUtility to provide station scanning functionality, -whereby the frequency spectrum is searched, pausing for a specified amount of -time when a station is found. -*/ -class CMMTunerScannerUtility : public CBase -{ - friend class CMMTunerUtility::CBody; -public: - - IMPORT_C ~CMMTunerScannerUtility(); - - /** - Continuously scan for a radio station, pausing for the time specified before - continuing on to the next station. Call StopScan to select the currently tuned - station. The search is limited to the specified band. - - @note The control of a CMMTunerUtility object must have been passed to this - class (using TransferTunerControl) before this function is called. - - @param aBand The band to which aStartFrequency belongs - @param aSearchDirect The direction to search in - @param aPauseDuration Time to pause at each station - @param aCircularScan If set to ETrue the station scan will loop back to the other - end of the band once the end of the band has been reached. (Defaults to ETrue) - */ - IMPORT_C void StationScan(CMMTunerUtility::TSearchDirection aSearchDirection, - TTimeIntervalMicroSeconds32 aPauseDuration - ); - - /** - Stop scanning and use the currently tuned station - - @return ETrue if a station is tuned, EFalse otherwise - */ - IMPORT_C TBool StopScan(); - -protected: - /** - Factory function to create a new CMMTunerScannerUtility. - - @param aTuner The tuner with which to perform the scanning. - @leave KErrNoMemory Out of memory. - @return A newly contructed tuner scanner utility. - */ - static CMMTunerScannerUtility* NewL(CMMTunerUtility& aTuner,CMMTunerUtility::TTunerBand aBand); - -private: - CMMTunerScannerUtility(); -private: - class CBody; - CBody* iBody; - -}; - - -/** Programme Station name, 8 characters */ -typedef TBuf<8> TRdsStationName; -/** Programme Type Name, 8 characters */ -typedef TBuf<8> TRdsProgrammeTypeName; -/** RDS Programme Identifier, a unique ID for each radio station */ -typedef TInt TRdsProgrammeIdentifier; - -/** -Programme Item Number - identifies the start time of the current programme, -as published by the broadcaster. -*/ -class TRdsProgrammeItemNumber -{ -public: - /** The day of the month of the broadcast, in the range 1-31 */ - TInt iDayOfMonth; - /** The hour of the day, in the range 0-23 */ - TInt iHour; - /** The minute past the hour, in the range 0-59 */ - TInt iMinute; -public: - inline TInt operator==(const TRdsProgrammeItemNumber& aPin) const; - inline TInt operator!=(const TRdsProgrammeItemNumber& aPin) const; -}; - -/** -An RDS extended country code. The meaning of a value of this type is defined -by the RDS specification, IEC62106. -*/ -typedef TInt TRdsCountryCode; - -/** -An RDS language identification code. The meaning of a value of this type is -defined by the RDS specification, IEC62106. -*/ -typedef TInt TRdsLanguageIdentifier; - -/** -RDS Programme Type. - -The interpretation of values of this type depends on the origin of the RDS -broadcast: in North America, a slightly different standard, RBDS, is used. -These PTY codes are defined by static values KRbdsPtyXxxxx, for example -KRbdsPtySoftRock. - -Elsewhere, including Europe, the RDS standard is used. In these areas, the -PTY codes are defined by static values KRdsPtyXxxxx, for example -KRdsPtyChildrensProgrammes. - -In all other important aspects, the European RDS and North American RBDS -standards are identical. -*/ -typedef TInt TRdsProgrammeType; - -/** No programme type or undefined */ -const static TRdsProgrammeType KRdsPtyNone = 0; -/** News */ -const static TRdsProgrammeType KRdsPtyNews = 1; -/** CurrentAffairs */ -const static TRdsProgrammeType KRdsPtyCurrentAffairs = 2; -/** Information */ -const static TRdsProgrammeType KRdsPtyInformation = 3; -/** Sport */ -const static TRdsProgrammeType KRdsPtySport = 4; -/** Education */ -const static TRdsProgrammeType KRdsPtyEducation = 5; -/** Drama */ -const static TRdsProgrammeType KRdsPtyDrama = 6; -/** Culture */ -const static TRdsProgrammeType KRdsPtyCulture = 7; -/** Science */ -const static TRdsProgrammeType KRdsPtyScience = 8; -/** VariedSpeech */ -const static TRdsProgrammeType KRdsPtyVariedSpeech = 9; -/** PopMusic */ -const static TRdsProgrammeType KRdsPtyPopMusic = 10; -/** RockMusic */ -const static TRdsProgrammeType KRdsPtyRockMusic = 11; -/** EasyListening */ -const static TRdsProgrammeType KRdsPtyEasyListening = 12; -/** LightClassical */ -const static TRdsProgrammeType KRdsPtyLightClassical = 13; -/** SeriousClassics */ -const static TRdsProgrammeType KRdsPtySeriousClassical = 14; -/** OtherMusic */ -const static TRdsProgrammeType KRdsPtyOtherMusic = 15; -/** Weather */ -const static TRdsProgrammeType KRdsPtyWeather = 16; -/** Finance */ -const static TRdsProgrammeType KRdsPtyFinance = 17; -/** ChildrensProgrammes */ -const static TRdsProgrammeType KRdsPtyChildrensProgrammes = 18; -/** SocialAffairs */ -const static TRdsProgrammeType KRdsPtySocialAffairs = 19; -/** Religion */ -const static TRdsProgrammeType KRdsPtyReligion = 20; -/** PhoneIn */ -const static TRdsProgrammeType KRdsPtyPhoneIn = 21; -/** Travel */ -const static TRdsProgrammeType KRdsPtyTravel = 22; -/** Leisure */ -const static TRdsProgrammeType KRdsPtyLeisure = 23; -/** JazzMusic */ -const static TRdsProgrammeType KRdsPtyJazzMusic = 24; -/** CountryMusic */ -const static TRdsProgrammeType KRdsPtyCountryMusic = 25; -/** NationalMusic */ -const static TRdsProgrammeType KRdsPtyNationalMusic = 26; -/** OldiesMusic */ -const static TRdsProgrammeType KRdsPtyOldiesMusic = 27; -/** FolkMusic */ -const static TRdsProgrammeType KRdsPtyFolkMusic = 28; -/** Documentary */ -const static TRdsProgrammeType KRdsPtyDocumentary = 29; -/** AlarmTest */ -const static TRdsProgrammeType KRdsPtyAlarmTest = 30; -/** Alarm */ -const static TRdsProgrammeType KRdsPtyAlarm = 31; - - -/** No programme type or undefined */ -const static TRdsProgrammeType KRbdsPtyNone = 0; -/** News */ -const static TRdsProgrammeType KRbdsPtyNews = 1; -/** Informaion */ -const static TRdsProgrammeType KRbdsPtyInformation = 2; -/** Sports */ -const static TRdsProgrammeType KRbdsPtySports = 3; -/** Talk */ -const static TRdsProgrammeType KRbdsPtyTalk = 4; -/** Rock */ -const static TRdsProgrammeType KRbdsPtyRock = 5; -/** Classic Rock */ -const static TRdsProgrammeType KRbdsPtyClassicRock = 6; -/** Adult Hits */ -const static TRdsProgrammeType KRbdsPtyAdultHits = 7; -/** Soft Rock */ -const static TRdsProgrammeType KRbdsPtySoftRock = 8; -/** Top 40 */ -const static TRdsProgrammeType KRbdsPtyTop40 = 9; -/** Country */ -const static TRdsProgrammeType KRbdsPtyCountry = 10; -/** Oldies */ -const static TRdsProgrammeType KRbdsPtyOldies = 11; -/** Soft */ -const static TRdsProgrammeType KRbdsPtySoft = 12; -/** Nostalgia */ -const static TRdsProgrammeType KRbdsPtyNostalgia = 13; -/** Jazz */ -const static TRdsProgrammeType KRbdsPtyJazz = 14; -/** Classical */ -const static TRdsProgrammeType KRbdsPtyClassical = 15; -/** Rhythm and Blues */ -const static TRdsProgrammeType KRbdsPtyRhythmAndBlues = 16; -/** Soft Rhythm and Blues */ -const static TRdsProgrammeType KRbdsPtySoftRhythmAndBlues = 17; -/** Language */ -const static TRdsProgrammeType KRbdsPtyLanguage = 18; -/** Religious Music */ -const static TRdsProgrammeType KRbdsPtyReligiousMusic = 19; -/** Religious Talk */ -const static TRdsProgrammeType KRbdsPtyReligiousTalk = 20; -/** Personality */ -const static TRdsProgrammeType KRbdsPtyPersonality = 21; -/** Public */ -const static TRdsProgrammeType KRbdsPtyPublic = 22; -/** College */ -const static TRdsProgrammeType KRbdsPtyCollege = 23; -/** Unassigned */ -const static TRdsProgrammeType KRbdsPtyUnassigned1 = 24; -/** Unassigned */ -const static TRdsProgrammeType KRbdsPtyUnassigned2 = 25; -/** Unassigned */ -const static TRdsProgrammeType KRbdsPtyUnassigned3 = 26; -/** Unassigned */ -const static TRdsProgrammeType KRbdsPtyUnassigned4 = 27; -/** Unassigned */ -const static TRdsProgrammeType KRbdsPtyUnassigned5 = 28; -/** Weather */ -const static TRdsProgrammeType KRbdsPtyWeather = 29; -/** Emergency Test */ -const static TRdsProgrammeType KRbdsPtyEmergencyTest = 30; -/** Emergency */ -const static TRdsProgrammeType KRbdsPtyEmergency = 31; - -/** -The RDS Capabilities class defines the capabilities of the RDS tuner on the -device, as retrieved using the function GetRdsCapabilities. -*/ -class TRdsCapabilities -{ -public: - /** RDS Function Bit Flags */ - enum TRdsFunctions - { - /** Traffic Announcement */ - ERdsFunctionTa = 0x01, - /** Regional Links */ - ERdsFunctionRegLink = 0x02, - /** News Announcement */ - ERdsFunctionNa = 0x04, - /** Programme Type */ - ERdsFunctionPty = 0x08, - /** Clock Time */ - ERdsFunctionCt = 0x10, - /** Enhanced Other Networks */ - ERdsFunctionEon = 0x20, - /** Alternative Frequency */ - ERdsFunctionAf = 0x40 - }; -public: - /** Bitfield as defined by ERdsFunctions with the bits of the supported functions set */ - TUint32 iRdsFunctions; -}; - -class MMMRdsDataObserver; -class MMMRdsEonObserver; -class MMMRdsStateChangeObserver; -class MMMRdsAnnouncementObserver; - -/** -This class represents the basic RDS data associated with an RDS station. -*/ -class TRdsData -{ -public: - inline TRdsData(); -public: - /** - Enumeration to indicate a subset of the members of class TRdsData. These values should - be bitwise or'ed together to indicate which members belong in a set. - */ - enum TField - { - /** Indicates the the member iPi is in a set */ - EProgrammeIdentifier = 0x001, - /** Indicates the the member iPs is in a set */ - EStationName = 0x002, - /** Indicates the the member iTp is in a set */ - ETrafficProgramme = 0x004, - /** Indicates the the member iTa is in a set */ - ETrafficAnnouncement = 0x008, - /** Indicates the the member iPty is in a set */ - EProgrammeType = 0x010, - /** Indicates the the member iPtyn is in a set */ - EProgrammeTypeName = 0x020, - /** Indicates the the member iPin is in a set */ - EProgrammeItemNumber = 0x040, - /** Indicates the the member iMs is in a set */ - EMusicSpeech = 0x080, - /** Indicates the the member iBroadcastLanguage is in a set */ - EBroadcastLanguage = 0x100, - /** Indicates the the member iEcc is in a set */ - EExtendedCountryCode = 0x200 - }; - /** - A value indicating a set containig all RDS data encapsulated by class TRdsData. - */ - const static TUint32 KAllRdsData = (EProgrammeIdentifier | EStationName | ETrafficProgramme | ETrafficAnnouncement - | EProgrammeType | EProgrammeTypeName | EProgrammeItemNumber | EMusicSpeech - | EBroadcastLanguage | EExtendedCountryCode); -public: - /** Programme Identifier of the station */ - TRdsProgrammeIdentifier iPi; - /** Programme Station name of the station */ - TRdsStationName iPs; - /** Value of the Traffic Programme flag of the station */ - TBool iTp; - /** Value of the Traffic Announcement flag of the station */ - TBool iTa; - /** Programme Type of the station */ - TRdsProgrammeType iPty; - /** Programme Type Name of the station */ - TRdsProgrammeTypeName iPtyn; - /** Programme Item Number of the station */ - TRdsProgrammeItemNumber iPin; - /** Value of the Music Speech flag of the station. EFalse indicates the speech is being - broadcast at present. ETrue indicates that music is being broadcast, or that the flag is - not in use by the broadcaster. */ - TBool iMs; - /** The current language of the broadcast */ - TRdsLanguageIdentifier iBroadcastLanguage; - /** The Extended Country Code of the station */ - TRdsCountryCode iEcc; -}; - -/** -Class representing a station broadcast as an Enhanced Other Networks station. -*/ -class TEonStation -{ -public: - /** - Enumeration to indicate a subset of the members of class TEonStation. These values should - be bitwise or'ed together to indicate which members belong in a set. - */ - enum TField - { - /** Indicates that member iProgrammeIdentifier is valid. */ - EProgrammeIdentifier= 0x01, - /** Indicates that member iStationName is valid. */ - EStationName = 0x02, - /** Indicates that member iProgrammeType is valid. */ - EProgrammeType = 0x04, - /** Indicates that member iTrafficProgramme is valid. */ - ETrafficProgramme = 0x08, - /** Indicates that member iTrafficAnnouncement is valid. */ - ETrafficAnnouncement= 0x10, - /** Indicates that member iProgrammeItemNumber is valid. */ - EProgrammeItemNumber= 0x20, - /** Indicates that member iNoFrequencies is valid. */ - ENoFrequencies = 0x40, - /** Indicates that member iNoMappedFrequencies is valid. */ - ENoMappedFrequencies= 0x80 - }; -public: - /** The unique identifier of this station */ - TRdsProgrammeIdentifier iProgrammeIdentifier; - /** The textual name of this station */ - TRdsStationName iStationName; - /** The current programme type (PTY) of this station */ - TRdsProgrammeType iProgrammeType; - /** Indicates if this station broadcasts traffic programmes */ - TBool iTrafficProgramme; - /** Indicates if this station is currently broadcasting a traffic announcement */ - TBool iTrafficAnnouncement; - /** The programme item number (PIN) of the current broadcast on this station. */ - TRdsProgrammeItemNumber iProgrammeItemNumber; - /** - The number of frequencies associated with this station. If this number is zero, - it may be that the EON station uses the mapped frequencies method instead. See - iNoMappedFrequencies. - */ - TInt iNoFrequencies; - /** - The number of mapped frequencies associated with this station. If this number is - zero, it may be that the EON station uses a flat frequency list instead. See - iNoFrequencies. - */ - TInt iNoMappedFrequencies; - /** - Indicates the subset of fields of the class that are valid. Bits are set according to enumeration - TEonStation::TField - */ - TUint32 iValid; -}; - -/** -Mapped frequencies can be broadcast as a part of the EON information. They relate the -current tuning frequency with the frequency which the referred EON station will be -broadcast on. -*/ -class TEonMappedFrequency -{ -public: - inline TEonMappedFrequency(TFrequency aTuningFrequency, TFrequency aMappedFrequency); -public: - /** The current tuning frequency, relating to the station broadcasting the EON informarion. */ - TFrequency iTuningFrequency; - /** - The mapped frequency. If iTunedFrequency matches the currently tuned frequency, the - EON station will be broadcast on this frequency. - */ - TFrequency iMappedFrequency; -}; - -/** -The RDS class augments the tuner API to give access to the RDS capabilities -of the device. As such additional tuner technologies can be supported without -changing the Tuner API. - -Note that despite this class being names 'RDS', it is capable of supporting both -the RDS standard, and the North American equivilant RBDS. The only important difference -from the APIs perspective is the interpretation of the Programme Type (PTY) codes. See -TRdsProgrammeType for more information. -*/ -class CMMRdsTunerUtility : public CBase -{ - friend class CMMTunerUtility::CBody; -public: - /** RDS Announcement Type */ - enum TAnnouncementType - { - /** Traffic announcement */ - ERdsTrafficAnnouncement, - /** News announcement */ - ERdsNewsAnnouncement - }; -public: - /** - Factory function to create a new instance of the RDS Tuner API - - @param aTuner A RDS capable tuner object (check using CMMTunerUtility::GetCapabilities()) - @param aObserver The observer of the tuner to receive asynchronous completion messages. - @leave KErrNoMemory Out of memory - @leave KErrNotFound CMMRdsTunerUtility object is not present - @leave KErrNotSupported RDS is not supported by the tuner - @return A pointer and ownership of a fully constructed CMMRdsTunerUtility object - */ - IMPORT_C static CMMRdsTunerUtility* NewL(CMMTunerUtility& aTuner, MMMTunerObserver& aObserver, CMMTunerUtility::TTunerBand aBand); - - IMPORT_C ~CMMRdsTunerUtility(); - - /** - Get the RDS capabilities of the device - - @param aCaps The capabilities object to fill - @return A standard system error code - */ - IMPORT_C TInt GetRdsCapabilities(TRdsCapabilities& aCaps) const; - - /** - Find a radio station which contains RDS data starting at the start frequency - and searching in the direction specified (i.e. Up or down). - - @note this function is subject to the same access control scheme as the Tune - methods of CMMTunerUtility - - @param aStartFrequency The frequency to start searching from, or 0 to start at the - beginning of the stated band. - @param aBand The frequency band to search. This must be a FM band. - @param aSearchDirection The direction to search in - @param 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 StationSearchByRds(TFrequency aStartFrequency, - CMMTunerUtility::TSearchDirection aSearchDirection - ); - - /** - Find a radio station, of the specified programme type starting at the start - frequency and searching in the direction specified (i.e. Up or down). - - @note this function is subject to the same access control scheme as the Tune - methods of CMMTunerUtility - - @param aProgType The type of programme to search for - @param aStartFrequency The frequency to start searching from, or 0 to start at the - beginning of the stated band. - @param aBand The frequency band to search. This must be a FM band. - @param aSearchDirection The direction to search in - @param 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 StationSearchByProgrammeType( - TRdsProgrammeType aProgType, - TFrequency aStartFrequency, - CMMTunerUtility::TSearchDirection aSearchDirection - ); - - /** - Find a radio station, with the specified programme identifier starting at the - start frequency and searching in the direction specified (i.e. Up or down). - - @note this function is subject to the same access control scheme as the Tune - methods of CMMTunerUtility - - @param aPi The programme identifier of the station to search for - @param aStartFrequency The frequency to start searching from, or 0 to start at the - beginning of the stated band. - @param aBand The frequency band to search. This must be a FM band. - @param aSearchDirection The direction to search in - @param 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 StationSearchByProgrammeIdentifier( - TRdsProgrammeIdentifier aPi, - TFrequency aStartFrequency, - CMMTunerUtility::TSearchDirection aSearchDirection - ); - - /** - Find a radio station, with the specified traffic programme flag value starting at - the start frequency and searching in the direction specified (i.e. Up or down). - - @note this function is subject to the same access control scheme as the Tune - methods of CMMTunerUtility - - @param aTp The TP flag value of a station to search for - @param aStartFrequency The frequency to start searching from, or 0 to start at the - beginning of the stated band. - @param aBand The frequency band to search. This must be a FM band. - @param aSearchDirection The direction to search in - @param 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 StationSearchByTrafficProgramme( - TBool aTp, - TFrequency aStartFrequency, - CMMTunerUtility::TSearchDirection aSearchDirection - ); - - /** - Cancels an ongoing RDS search as initiated by one of the functions - StationSearchByRds, StationSearchByProgrammeType, - StationSearchByProgrammeIdentifier or StationSearchByTrafficProgramme. The - asynchronous callback will not occur if this is called. - - Has not affect if no RDS search operation is ongoing. - */ - IMPORT_C void CancelRdsSearch(); - - /** - Requests notifications when all RDS data become invalid due to the tuner being - retuned. - - @param aObserver The client to be notified. - @param aWhichData The subset of data for which change notifications are required. - @return A standard system wide error code. - */ - IMPORT_C TInt NotifyRdsDataChange(MMMRdsDataObserver& aObserver, TUint32 aWhichData = TRdsData::KAllRdsData); - - /** - Cancel a NotifyRdsDataChange request. - */ - IMPORT_C void CancelNotifyRdsDataChange(); - - /** - Request some RDS data. This will complete immediately with whatever RDS data have already been - received. - - When this function returns, and data that was requested but is not indicated to be - valid can be assumed not to have been received. - - @param aData The RDS data will be written to this variable. - @param aValid On return, indicates a subset of RDS data that are valid. - @param aWhichData The subset of RDS data that are being requested. - @return A standard system wide error code. - */ - IMPORT_C TInt GetRdsData(TRdsData& aData, TUint32& aValid, TUint32 aWhichData = TRdsData::KAllRdsData) const; - - /** - Converts an RDS language identifier into a Symbian TLanguage type. Note that not all - languages defined by the RDS specification IEC62106 are present in the TLanguage - enumeration; in these cases, a value of ELangOther will be returned. - - @param aRdsLangId An RDS language identification code - @return The corresponding TLanguage member, or ELangOther if none exists. - */ - IMPORT_C static TLanguage ConvertRdsLanguageId(TRdsLanguageIdentifier aRdsLangId); - - /** - Get the length of the available radio text. If no radio text is available this - function will return KErrNotFound. The maximum possible length for radio text is 64 characters. - - @param aLength The variable to set to the length of the avaiable radio text - @return A standard system error code. - */ - IMPORT_C TInt GetRadioTextLength(TUint& aLength) const; - - /** - Get the radio text. If no radio text is available, this will return KErrNotFound. In this - case, a client can call NotifyRadioText to receive a notification when it is received. - - The radio text will have been converted to unicode, eliminating any control characters - within it. - - @param aRadioText The descriptor to fill with the radio text - @return A standard system error code - */ - IMPORT_C TInt GetRadioText(TDes& aRadioText) const; - - /** - Request notification when the radio text is received or changes. - - @param aObserver The client to be notified when the radio text is received or changes. - @return A standard system wide error code. - */ - IMPORT_C TInt NotifyRadioText(MMMRdsDataObserver& aObserver); - - /** - Cancel a NotifyRadioText request. - */ - IMPORT_C void CancelNotifyRadioText(); - - /** - Turns regional link function on or off depending on the value of the parameter. - A value of ETrue should be passed if you wish to stay tuned to the currently - tuned local station regardless of signal quality and signal strength. - i.e. don't switch to another local station in the region. - - @param aRegOn ETrue to turn regional link on, EFalse to turn it off - @return A standard system error code - */ - IMPORT_C TInt SetRegionalLink(TBool aRegOn); - - /** - Finds out if the regional link function is currently on or off. - - @param aRegOn This will be set to ETrue on return if and only if the regional - link function is currently enabled. - @return A standard system error code. - */ - IMPORT_C TInt GetRegionalLink(TBool& aRegOn) const; - - /** - Turn the travel announcement function on or off depending on the value of the - parameter. A value of ETrue turns on Traffic Announcements, EFalse turns them off. - - If Traffic announcements are disabled while the tuner is retuned to a traffic - announcement, the tuner will not revert to the original frequency. To revert to - the original frequency, StopAnnouncement() must be called before the traffic - announcement feature is disabled. - - @param aTaOn ETrue to turn TA on, EFalse to turn it off - @return A standard system error code - */ - IMPORT_C TInt SetTrafficAnnouncement(TBool aTaOn); - - /** - Finds out if the traffic announcement function is currently enabled or not. - - @param aTaOn This is set to ETrue on return if and only if the traffic - announcement function is currenly enabled. - */ - IMPORT_C TInt GetTrafficAnnouncement(TBool& aTaOn) const; - - /** - Set the absolute volume to apply during a traffic or news announcement. - - @param aVolume The volume to use. Must be between 0 and MaxVolume. - @return A standard system error code. - */ - IMPORT_C TInt SetAnnouncementVolume(TInt aVolume); - - /** - Find the current absolute volume level used for news of traffic annoucements. - - @param aVolume This will be set to the current volume used for annoucements. - @return A standard system error code, KErrNotFound if a annoucement volume offset has been set. - use. - */ - IMPORT_C TInt GetAnnouncementVolume(TInt& aVolume) const; - - /** - Set the offset to the system volume level to apply during a traffic or news announcement - - @param aVolumeOffset The offset to the volume level to set for announcements. Must be between -MaxVolume and MaxVolume inclusive. - the actual volume with the offset applied will be clipped between 0 and MaxVolume if the offset would - otherwise result in a volume outside this range. - @return A standard system error code - */ - IMPORT_C TInt SetAnnouncementVolumeOffset(TInt aVolumeOffset); - - /** - Find the current offset of the system volume that applies during traffic and news announcements. - - @param aVolumeOffset This will be set to the current traffic and news announcement offset on return. - @return A standard system error code, KErrNotFound if an absolute annoucement volume has been set. - */ - IMPORT_C TInt GetAnnouncementVolumeOffset(TInt& aVolumeOffset) const; - - /** - Turn the news announcement function on or off depending on the value of the - parameter. The news announcement function when enabled causes the radio to - retune to a station when that station is broadcasting a news report. When the - news announcement is finished the radio will tune back to the original station. - A value of ETrue turns on News Announcements, EFalse turns them off. - - If News announcements are disabled while the tuner is retuned to a news - announcement, the tuner will not revert to the original frequency. To revert to - the original frequency, StopAnnouncement() must be called before the news - announcement feature is disabled. - - @param aNaOn ETrue to turn NA on, EFalse to turn it off - @return A standard system error code - */ - IMPORT_C TInt SetNewsAnnouncement(TBool aNaOn); - - /** - Finds out whether the news announcement function is on or off. - - @param aNaOn This will be set to ETrue if and only if the new announcement - function is currently on. - @return A standard system error code. - */ - IMPORT_C TInt GetNewsAnnouncement(TBool& aNaOn) const; - - /** - Cancels any current announcement, reverting to the original frequency. The announcement - feature will remain enabled. If no announcement is currently happening, this function - has no affect. This can be used for both News and Traffic announcements. - - @return A standard system error code. KErrNone if an announcement was successfully - stopped, or KErrNotReady if no announcement is currently happening. - */ - IMPORT_C TInt StopAnnouncement(); - - /** - Turns alternative frequency function on or off depending on the value of the parameter. - A value of ETrue should be passed if you wish to enable automatic retuning to the current - station on an alternative frequency. - - @param aAfOn ETrue to turn alternative frequency on, EFalse to turn it off - @return A standard system error code - */ - IMPORT_C TInt SetAlternativeFrequency(TBool aAfOn); - - /** - Finds out whether the alternative frequency function is on or off. - - @param aAfOn This will be set to ETrue if and only if the alternative frequency - function is currently on. - @return A standard system error code. - */ - IMPORT_C TInt GetAlternativeFrequency(TBool& aAfOn) const; - - /** - Requests a notification when RDS functionality is enabled or disabled, or when - the traffic announcement volume offset is changed. - - @param aObserver The class which is to be notified of the changes. - @return A standard system error code. - */ - IMPORT_C TInt NotifyRdsStateChange(MMMRdsStateChangeObserver& aObserver); - - /** - Cancels an outstanding RDS state change notification request. - */ - IMPORT_C void CancelNotifyRdsStateChange(); - - /** - Get the current RDS time. This is an asynchronous function due to the latency of - the RDS information becoming available. This information is broadcast at the start of - every minute, and is not cached for obvious reasons. Thus, whenever a request is made, - it will complete next time the Data and Time are broadcast. The RDS standard states - that this is broadcast within 0.1s of the start of a minute, and is accurate to one - minute. The latency of the notification reaching the application cannot be guarteed. - - @param aTimeAndDate The variable to set to the current RDS time and date - @param aStatus A TRequestStatus. This will be signalled when the request completes - and will contain the result of the request, this will be one of the system error codes. - */ - IMPORT_C void GetRdsTime(TPckg& aTimeAndDate, TRequestStatus& aStatus) const; - - /** - Cancel the GetRdsTime request - */ - IMPORT_C void CancelGetRdsTime(); - - /** - Request notification when a retune caused by an announcement occurs. This will be - a traffic or news announcement. A notification will be provided both at - the start of the announcement and at the end. - - @param aObserver The object wishing to receive announcement events - @return A standard system error code - */ - IMPORT_C TInt NotifyAnnouncement(MMMRdsAnnouncementObserver& aObserver); - - /** - Cancel the NotifyAnnouncement request - */ - IMPORT_C void CancelNotifyAnnouncement(); - - /** - Returns a list containing information about other networks broadcast with the currently tuned - programmme. This call will return immediately with whatever EON information is currently available. - Note that is is possible for this function to return no EON stations when several are being broadcast - simply because not enough RDS frames have been received yet. An interested application should make a - call to NotifyEonInfo to receive notifications when EON information is received or changes. - - @param aEonInfo An array to which the EON information will be appended. - */ - IMPORT_C void GetEonInfoL(RArray& aEonInfo) const; - - /** - Gets the frequencies assoicated with an EON station. This will complete immediately with whatever - frequencies are currently cached. An interested application should make a call to NotifyEonChange - to receive notifications when more frequencies are received. - - @param aEonStation the EON station to get the frequencies for - @param aFrequencies an array to which the frequencies associated with the given station will be - appended. - */ - IMPORT_C void GetEonFrequenciesL(const TEonStation& aEonStation, RArray& aFrequencies) const; - - /** - Gets the mapped frequencies associated with an EON station. This will complete immediately with whatever - mapped frequencies are currently cached. An interested application should make a call to NotifyEonChange - to receive notifications when more frequencies are received. - - @param aEonStation the EON station to get the mapped frequencies for - @param aMappedFrequencies an array to which the mapped frequencies associated with the given station - will be appended. - */ - IMPORT_C void GetEonMappedFrequenciesL(const TEonStation& aEonStation, RArray& aMappedFrequencies) const; - - /** - Request notification when the Enhanced Other Networks (EON) information changes. - - @param aObserver The client to be notifier when EON information changes or an error occurs. - */ - IMPORT_C TInt NotifyEonInfo(MMMRdsEonObserver& aObserver); - - /** - Cancels a NotifyEonInfo request. - */ - IMPORT_C void CancelNotifyEonInfo(); - - /** - Tunes to a station represented by a TEonStation. This will result to a callback to MtoTuneComplete. - - @param aEonStation The EON station that is to be tuned to. - */ - IMPORT_C void TuneToEonStation(const TEonStation& aEonStation); - - /** - Send a synchronous custom command to the RDS tuner. - - @param aFunction The function number to indicate which function is to be called - on the interface defined by the first IPC argument - @param aArgs The IPC arguments to send to the RDS 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 A standard system error code - */ - IMPORT_C TInt CustomCommandSync(TInt aFunction, const TIpcArgs& aArgs); - - /** - Send an asynchronous custom command to the RDS tuner. - - @param aFunction The function number to indicate which function is to be called - on the interface defined by the first IPC argument - @param aArgs The IPC arguments to send to the RDS 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. - @param 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 void CustomCommandAsync(TInt aFunction, const TIpcArgs& aArgs, TRequestStatus& aStatus); - -private: - CMMRdsTunerUtility(); -private: - class CBody; - CBody* iBody; - -}; - -/** -This mixin class should be implemented by applications wishing to receive notifications -when RDS data is received, changes or becomes invalid. Each method corresponds to a -particular request in CMMRdsTunerUtility. Only methods corresponding to requests in -CMMRdsTunerUtility that are used by a client need be implemented - empty default -implementations are provided. -*/ -class MMMRdsDataObserver -{ -public: - /** - Called when some error occurs which makes RDS data unavailable. - */ - virtual void MrdoError(TInt aError) = 0; - - /** - Called when some RDS data is received or has changed. - - Two subsets of the RDS data supplied are indicted: that which has changed and that which is - valid. This information can be interpreted as follows: - For an item of RDS data x: - valid(x) & !changed(x) => x was received before and has not changed - valid(x) & changed(x) => x has either just been received for the first time, or has just changed - !valid(x) & changed(x) => x is no longer available - !valid(x) & !changed(x) => x was not available before, and is still not available. - - When the tuner is retuned to a new station, all RDS data will be flushed. This will result in - a call to this function indicating that all RDS data has changed and is longer valid. - - @param aData The RDS data. - @param aValid Indicates a subset of aData that is valid (i.e. has been received) - @param aChanged Indicates a subset of aData that has changed since the last call to this function. - */ - virtual void MrdoDataReceived(const TRdsData& aData, TUint32 aValid, TUint32 aChanged) = 0; - - /** - Called when the RDS Radio Text (RT) is received, changes, or is no longer available. - - @param aRt The Radio Text message. This will be empty if aValid==EFalse. - @param aValid Indicates if the radio text is valid. - @param aChanges Indicates if the radio test has changed. - */ - virtual void MrdoRadioTextReceived(const TDesC& aRt, TBool aValid, TBool aChanged) = 0; -}; - -/** -The state change observer mixin class defines the interface via which changes to -the state of the RDS radio can be observed. These state changes will be a result -of a client enabling or disabling RDS functionality. -*/ -class MMMRdsStateChangeObserver -{ -public: - /** - Called when the regional link functionality is enabled/disabled. - - @param aNewRegLinkOn The new setting: ETrue if the regional link function has - just been enabled. - */ - virtual void MrscoRegionalLinkChanged(TBool aNewRegLinkOn) = 0; - - /** - Called when the traffic announcement functionality has just been enabled or - disabled. - - @param aNewTaOn ETrue if the TA function is now on, EFalse otherwise. - */ - virtual void MrscoTrafficAnnouncementChanged(TBool aNewTaOn) = 0; - - /** - Called when the traffic and news announcement volume offset is changed. A callback to - this method indicates the a volume offset is being used instead of an absolute volume. - - @param aOldOffset The announcement volume offset before the change - @param aNewOffset The announcement volume offset after the change - */ - virtual void MrscoAnnouncementVolumeOffsetChanged(TInt aOldOffset, TInt aNewOffset) = 0; - - /** - Called when the traffic an news announcement volume is changed. A callback to - this method indicates that an absolute volume is being used instead of volume offsets. - - @param aOldVolume The announcement volume before the change. - @param aNewVolume The announcement volume after the change. - */ - virtual void MrscoAnnouncementVolumeChanged(TInt aOldVolume, TInt aNewVolume) = 0; - - /** - Called when the news announcement functionality has just been enabled or - disabled. - - @param aNewNAOn ETrue if the NA function is now enabled, else EFalse. - */ - virtual void MrscoNewsAnnouncementChanged(TBool aNewNAOn) = 0; - - /** - Called when the alternative frequencies function is turned on or off. - - @param aNewAFOn ETrue if the AF function has just been turned on, else EFalse. - */ - virtual void MrscoAlternativeFrequenciesChanged(TBool aNewAFOn) = 0; -}; - - -/** -The Announcement Observer mixin class defines the interface via which -announcement events can be received. A client interested in such -information calls the function NotifyAnnouncement. -*/ -class MMMRdsAnnouncementObserver -{ -public: - /** - Called when an announcement starts - - @param aType The type of announcement (travel or news) - */ - virtual void MraoAnnouncementStart(CMMRdsTunerUtility::TAnnouncementType aType) = 0; - - /** - Called when an announcement ends - - @param aType The type of announcement (travel or news) - */ - virtual void MraoAnnouncementEnd(CMMRdsTunerUtility::TAnnouncementType aType) = 0; - - /** - Called when an error occurs which results in announcement notifications - becoming unavailable. - */ - virtual void MraoError(TInt aError) = 0; -}; - -/** -The enhanced other networks observer mixin class defines the interface via -which changes to the enhanced other networks information can be notified. A -client interested in such information calls the function NotifyEonChange. -*/ -class MMMRdsEonObserver -{ -public: - /** - Called when some details of an EON station change. The station can be referenced - to an existing one using it's Programme Identifier, which cannot change. - - @param aStation A TEonStation containing the new information about the station. - @param aChanged The subset of the members of aStation that have changed. Bits are - set according to TEonStation::TField. - */ - virtual void MreoEonStationChanged(const TEonStation& aStation, TUint32 aChanged) = 0; - - /** - Called when details of a new EON station are received. - - @param aStation A TEonStation containing the new information about the station. - */ - virtual void MreoNewEonStation(const TEonStation& aStation) = 0; - - /** - Called when details of all EON stations cease to be broadcast. This will - typically happen when the tuner is retuned. More EON stations may continue to be - recieved: this call does not indicate that EON information is no longer available. - */ - virtual void MreoAllEonStationsRemoved() = 0; - - /** - Called when details of an EON station cease to be broadcast. - - @param aPi The programme identifier of the EON station which has been removed. - */ - virtual void MreoEonStationRemoved(const TRdsProgrammeIdentifier& aPi) = 0; - - /** - Called when an error occurs resulting in EON notifications not being available. - */ - virtual void MreoError(TInt aError) = 0; -}; - -#include - -#endif // TUNER_H - -// End of file -