--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javauis/amms_akn/src_tuner/native/external_include/tuner.h Wed Oct 13 14:23:59 2010 +0300
@@ -0,0 +1,2535 @@
+/*
+* 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 <e32base.h>
+#include <MCustomCommand.h>
+#include <mmf/common/mmfbase.h>
+#include <mmf/common/mmfutilities.h>
+#include <mmf/common/mmfcontrollerframework.h>
+#include <mmf/common/mmfstandardcustomcommands.h>
+#include <mmf/common/mmfaudio.h>
+#include <Mda/Common/audio.h>
+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<TFourCC>& 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<TUint>& 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<TUint>& 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<TUint>& 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<TDateTime>& 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<TEonStation>& 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<TFrequency>& 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<TEonMappedFrequency>& 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 <b>all</b> 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 <tuner.inl>
+
+#endif // TUNER_H
+
+// End of file
+