--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmserv/radioutility/inc/RadioSession.h Tue Feb 02 01:08:46 2010 +0200
@@ -0,0 +1,1185 @@
+/*
+* Copyright (c) 2002-2004 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: This class is the main interface to the RadioServer. It implements
+* the client-side session. It also contains M-observer classes that
+* the client must implement to receive completion notification for
+* asynchronous requests and spontaneous event notifications.
+*
+*/
+
+
+
+#ifndef RADIOSESSION_H
+#define RADIOSESSION_H
+
+// INCLUDES
+#include <mmf/common/mmfbase.h>
+#include <mmf/common/mmfcontrollerframework.h>
+#include <mcustomcommand.h>
+
+#include "RadioServerData.h"
+
+// FORWARD DECLARATIONS
+class CRadioRequest;
+class CRadioEventHandler;
+
+// CLASS DECLARATION
+
+/**
+* Defines functions that client must implement in order to receive
+* events from the radio server.
+*
+* @lib RadioSession.lib
+* @since S60 3.0
+*/
+class MRadioObserver
+ {
+public: // New functions
+
+//********** Tuner related
+
+ /**
+ * Completion message for RequestTunerControl request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ */
+ virtual void RequestTunerControlComplete( TRadioServerError aError ) = 0;
+
+ /**
+ * Completion message for SetFrequencyRange request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ */
+ virtual void SetFrequencyRangeComplete( TRadioServerError aError ) = 0;
+
+ /**
+ * Completion message for SetFrequency request.
+ *
+ * @since S60 3.0
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ */
+ virtual void SetFrequencyComplete( TRadioServerError aError ) = 0;
+
+ /**
+ * Completion message for StationSeek request.
+ *
+ * @since S60 3.0
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aFrequency Valid only if aError is KErrNone. Contains the new frequency in Hz.
+ */
+ virtual void StationSeekComplete( TRadioServerError aError, TInt aFrequency ) = 0;
+
+ /**
+ * Event notification indicating FM transmitter status change. Radio receiver
+ * is turned off when FM transmitter is active.
+ *
+ * @since S60 3.2
+ * @param aActive ETrue if FM transmitter is active; EFalse otherwise.
+ */
+ virtual void RadioEventTransmitterStatusChange( TBool aActive ) = 0;
+
+ /**
+ * Event notification indicating antenna status change.
+ *
+ * @since S60 3.0
+ * @param aAttached ETrue if antenna is attached.
+ */
+ virtual void RadioEventAntennaStatusChange( TBool aAttached ) = 0;
+
+ /**
+ * Event notification indicating offline mode change.
+ *
+ * @since S60 3.0
+ * @param aOfflineMode ETrue if device is in offline mode.
+ */
+ virtual void RadioEventOfflineModeChange( TBool aOfflineMode ) = 0;
+
+ /**
+ * Event notification indicating frequency range change. This may be caused by
+ * other applications.
+ *
+ * @since S60 3.2
+ * @param aNewRange New frequency range.
+ */
+ virtual void RadioEventFrequencyRangeChanged( TRsFrequencyRange aNewRange ) = 0;
+
+ /**
+ * Event notification indicating frequency(Hz) change. This may be caused by
+ * other applications or RDS if AF/TA is enabled.
+ *
+ * @since S60 3.2
+ * @param aFrequency New frequency where tuner is currently tuned.
+ */
+ virtual void RadioEventFrequencyChange( TInt aFrequency ) = 0;
+
+ /**
+ * Event notification indicating forced mono status change.
+ *
+ * @since S60 3.2
+ * @param aForcedMono ETrue if forced mode is enabled; EFalse otherwise.
+ */
+ virtual void RadioEventForcedMonoChanged( TBool aForcedMono ) = 0;
+
+ /**
+ * Event notification indicating squelch (muting the frequencies without broadcast) status change.
+ *
+ * @since S60 3.2
+ * @param aSquelch ETrue if squelch is enabled; EFalse otherwise.
+ */
+ virtual void RadioEventSquelchChanged( TBool aSquelch ) = 0;
+
+//********** Player related
+
+ /**
+ * Event notification indicating radio player state change. This may be caused by
+ * other applications.
+ *
+ * @since S60 3.0
+ * @param aRadioOn ETrue if radio is playing, otherwise radio is off.
+ * @param aError Valid only if aRadioOn is EFalse. Contains the reason why radio is off.
+ */
+ virtual void RadioEventStateChange( TBool aRadioOn, TRadioServerError aError ) = 0;
+
+ /**
+ * Event notification indicating volume change.
+ *
+ * @since S60 3.2
+ * @param aVolume New volume.
+ */
+ virtual void RadioEventVolumeChange( TInt aVolume ) = 0;
+
+ /**
+ * Event notification indicating mute setting change.
+ *
+ * @since S60 3.2
+ * @param aMute ETrue indicates audio is muted.
+ */
+ virtual void RadioEventMuteChange( TBool aMute ) = 0;
+
+ /**
+ * Event notification indicating balance setting change.
+ *
+ * @since S60 3.2
+ * @param aLeftPercentage Left speaker volume percentage. This value ranges from 0 to 100.
+ * @param aRightPercentage Right speaker volume percentage. This value ranges from 0 to 100.
+ */
+ virtual void RadioEventBalanceChange( TInt aLeftPercentage, TInt aRightPercentage ) = 0;
+
+//********** RDS related
+
+ /**
+ * Completion message for StationSeekByPTY request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aFrequency The frequency(Hz) of the radio station that was found.
+ */
+ virtual void StationSeekByPTYComplete( TRadioServerError aError, TInt aFrequency ) = 0;
+
+ /**
+ * Completion message for StationSeekByTA request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aFrequency The frequency(Hz) of the radio station that was found.
+ */
+ virtual void StationSeekByTAComplete( TRadioServerError aError, TInt aFrequency ) = 0;
+
+ /**
+ * Completion message for StationSeekByTP request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aFrequency The frequency(Hz) of the radio station that was found.
+ */
+ virtual void StationSeekByTPComplete( TRadioServerError aError, TInt aFrequency ) = 0;
+
+ /**
+ * Completion message for GetFreqByPTY request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aFreqList Array of frequencies (Hz), valid only if aError is KErrNone.
+ */
+ virtual void GetFreqByPTYComplete( TRadioServerError aError, RArray<TInt>& aFreqList ) = 0;
+
+ /**
+ * Completion message for GetFreqByTA request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aFreqList Array of frequencies (Hz), valid only if aError is KErrNone.
+ */
+ virtual void GetFreqByTAComplete( TRadioServerError aError, RArray<TInt>& aFreqList ) = 0;
+
+ /**
+ * Completion message for StatGetPSByPTY request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aPsList Array of programme service names, valid only if aError is KErrNone.
+ */
+ virtual void GetPSByPTYComplete( TRadioServerError aError, RArray<TRsRdsPSName>& aPsList ) = 0;
+
+ /**
+ * Completion message for GetPSByTA request.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aPsList Array of programme service names, valid only if aError is KErrNone.
+ */
+ virtual void GetPSByTAComplete( TRadioServerError aError, RArray<TRsRdsPSName>& aPsList ) = 0;
+
+ /**
+ * Event notification indicating new Programme Identification(PI) is available.
+ *
+ * @since S60 3.2
+ * @param aPi Programme identification
+ */
+ virtual void RadioEventRdsDataPI( TInt aPi ) = 0;
+
+ /**
+ * Event notification indicating new Programme Type(PTY) is available.
+ *
+ * @since S60 3.2
+ * @param aPty Programme type
+ */
+ virtual void RadioEventRdsDataPTY( TRsRdsProgrammeType aPty ) = 0;
+
+ /**
+ * Event notification indicating new Programme Service(PS) is available.
+ *
+ * @since S60 3.2
+ * @param aPs Programme service
+ */
+ virtual void RadioEventRdsDataPS( TRsRdsPSName& aPs ) = 0;
+
+ /**
+ * Event notification indicating new Radio Text(RT) is available.
+ *
+ * @since S60 3.2
+ * @param aRt Radio text
+ */
+ virtual void RadioEventRdsDataRT( TRsRdsRadioText& aRt ) = 0;
+
+ /**
+ * Event notification indicating new Clock Time(CT) is available.
+ *
+ * @since S60 3.2
+ * @param aCt Clock time
+ */
+ virtual void RadioEventRdsDataCT( TDateTime& aCt ) = 0;
+
+ /**
+ * Event notification indicating Traffice Announcement(TA) status change.
+ *
+ * @since S60 3.2
+ * @param aTaOn ETrue indicates that Traffic Announcement is on.
+ */
+ virtual void RadioEventRdsDataTA( TBool aTaOn ) = 0;
+
+ /**
+ * Event notification indicating new Radio Text+(RT+) is available.
+ *
+ * @since S60 3.2
+ * @param aRtPlusClass Radio text plus class
+ * @param aRtPlusData Radio text plus data
+ */
+ virtual void RadioEventRdsDataRTplus( TRsRdsRTplusClass aRtPlusClass, TRsRdsRadioText& aRtPlusData ) = 0;
+
+ /**
+ * Event notification indicating the beginning of Alternate Frequency(AF) search.
+ *
+ * @since S60 3.2
+ */
+ virtual void RadioEventRdsSearchBeginAF() = 0;
+
+ /**
+ * Event notification indicating the end of Alternate Frequency(AF) search.
+ *
+ * @since S60 3.2
+ * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.
+ * @param aFrequency The frequency(Hz) of the radio station that was found.
+ */
+ virtual void RadioEventRdsSearchEndAF( TRadioServerError aError, TInt aFrequency ) = 0;
+
+ /**
+ * Event notification indicating station change to another frequency(Hz) that is
+ * broadcasting Traffic Announcement(TA).
+ *
+ * @since S60 3.2
+ * @param aFrequency The frequency(Hz) of the radio station that was found.
+ */
+ virtual void RadioEventRdsStationChangeTA( TInt aFrequency ) = 0;
+
+ /**
+ * Event notification indicating automatic switching (AF) setting change.
+ *
+ * @since S60 3.2
+ * @param aAuto ETrue indicates that automatic switching is on.
+ */
+ virtual void RadioEventRdsAutomaticSwitchingChange( TBool aAuto ) = 0;
+
+ /**
+ * Event notification indicating automatic traffic announcement setting change.
+ *
+ * @since S60 3.2
+ * @param aAuto ETrue indicates that automatic traffic announcement is on.
+ */
+ virtual void RadioEventRdsAutomaticTrafficAnnouncement( TBool aAuto ) = 0;
+
+ /**
+ * Event notification indicating RDS signal status change (i.e. signal is lost/restored).
+ *
+ * @since S60 3.2
+ * @param aSignal ETrue indicates that RDS signal is available in the tuned frequency.
+ */
+ virtual void RadioEventRdsSignalChange( TBool aSignal ) = 0;
+ };
+
+/**
+* Main interface to the Radio Server.
+* Implements the client-side session.
+*
+* @lib RadioSession.lib
+* @since S60 3.0
+*/
+class RRadioSession : public RSessionBase,
+ public MCustomCommand
+ {
+public: // Constructors and destructor
+
+ /**
+ * C++ default constructor.
+ */
+ IMPORT_C RRadioSession();
+
+public: // New functions
+
+ /**
+ * Connects a client to the radio server.
+ * @since S60 3.0
+ *
+ * @param aObserver The observer object for receiving async completion callbacks.
+ * @param aPrimaryClient Indicates whether the client is a primary client. Primary
+ * clients are clients that can control the radio tuner such as FM Radio Application,
+ * Visual Radio, or a Java Radio App. Non-primary clients are observers of the tuner,
+ * player, and RDS utilities and cannot exist without a primary client such as Active
+ * Idle, Cover UI, or a smart accessory driver.
+ * @return A standard system error code.
+ */
+ IMPORT_C TInt Connect( MRadioObserver& aObserver, TBool aPrimaryClient );
+
+ /**
+ * Gets the client side version number.
+ *
+ * @since S60 3.0
+ * @return The client side version number.
+ */
+ IMPORT_C TVersion Version() const;
+
+ /**
+ * Closes connection to the radio server.
+ *
+ * @since S60 3.0
+ */
+ IMPORT_C void Close();
+
+//********** TunerUtility control begins
+
+ /**
+ * Request for control of a tuner. If this method returns KErrNone, control of
+ * the tuner has been granted. Control to the tuner must be granted before any
+ * other request can be made.
+ *
+ * @since S60 3.2
+ * @param Tuner type (e.g. FM, AM)
+ * @return A standard system error code.
+ * @see MRadioObserver::RequestTunerControlComplete
+ */
+ IMPORT_C void RequestTunerControl( TRsTuner aTuner );
+
+ /**
+ * Get the capabilities of the radio on the device.
+ *
+ * @since S60 3.2
+ * @param aCaps The capabilities object to fill
+ * @return A standard system error code.
+ */
+ IMPORT_C TInt GetTunerCapabilities( TRsTunerCapabilities& aCaps ) const;
+
+ /**
+ * EnableTunerInOfflineMode on the device.
+ *
+ * @since S60 3.2
+ * @param aEnable ETrue to enable tuner functions in offline mode, EFalse to disable.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt EnableTunerInOfflineMode( TBool aEnable );
+
+ /**
+ * Asynchronous request to set the frequency range. If the frequency range is not set,
+ * it will be defaulted to ERsTunerFM.
+ *
+ * @since S60 3.2
+ * @param aRange Frequency range
+ * @see MRadioObserver::SetFrequencyRangeComplete
+ */
+ IMPORT_C void SetFrequencyRange( TRsFrequencyRange aRange );
+
+ /**
+ * Cancels an outstanding SetFrequencyRange request. Note that SetFrequencyRange may
+ * complete before cancel can occur and a callback may occur.
+ *
+ * @since S60 3.2
+ * @return A standard system error code.
+ */
+ IMPORT_C void CancelSetFrequencyRange();
+
+ /**
+ * Get the current frequency range. It also returns the minimum and maximum frequencies(Hz)
+ * for the returned range.
+ *
+ * @since S60 3.2
+ * @param aRange On return contains the current frequency range.
+ * @param aMinFreq On return contains the minimum frequency for the current frequency range.
+ * @param aMaxFreq On return contains the maximum frequency for the current frequency range.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetFrequencyRange( TRsFrequencyRange& aRange, TInt& aMinFreq, TInt& aMaxFreq ) const;
+
+ /**
+ * Asynchronous request to tune the tuner to the specified frequency.
+ *
+ * @since S60 3.2
+ * @param aFrequency The frequency (Hz) to tune to
+ * @see MRadioObserver::SetFrequecyComplete
+ */
+ IMPORT_C void SetFrequency( TInt aFrequency );
+
+ /**
+ * Cancels an outstanding SetFrequency request. Note that SetFrequency may complete before
+ * cancel can occur and a callback to MRadioObserver::SetFrequencyComplete may occur.
+ *
+ * @since S60 3.0
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C void CancelSetFrequency();
+
+ /**
+ * Get the current frequency.
+ *
+ * @since S60 3.2
+ * @param aFrequency On return contains the current frequency(Hz).
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetFrequency( TInt& aFrequency ) const;
+
+ /**
+ * Asynchronous request to find a radio station, starting from current frequency and
+ * seaching in the direction specified (i.e. up or down).
+ *
+ * @since S60 3.0
+ * @param aSeekUp Search direction
+ * @see MRadioObserver::StationSeekComplete
+ */
+ IMPORT_C void StationSeek( TBool aUpwards );
+
+ /**
+ * Cancels an outstanding StationSeek request. Note that StationSeek may complete before
+ * cancel can occur and a callback to MRadioObserver::StationSeekComplete may occur.
+ *
+ * @since S60 3.0
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C void CancelStationSeek();
+
+ /**
+ * Gets the signal strength of the currently tuned signal.
+ *
+ * @since S60 3.2
+ * @param aStrength On return contains the current signal strength.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetSignalStrength( TInt& aSignalStrength ) const;
+
+ /**
+ * Gets the maximum possible signal strength of a tuned signal.
+ *
+ * @since S60 3.2
+ * @param aMaxStrength On return contains the maximum signal strength.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetMaxSignalStrength( TInt& aMaxSignalStrength ) const;
+
+ /**
+ * Get the stereo mode of the radio.
+ *
+ * @since S60 3.2
+ * @param aStereo On return, will be ETrue if signal is stereo.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetStereoMode( TBool& aStereo ) const;
+
+ /**
+ * Indicates whether the reception should be forced into monophonic mode.
+ *
+ * @since S60 3.2
+ * @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/RadioServer error code.
+ */
+ IMPORT_C TInt ForceMonoReception( TBool aForcedMono );
+
+ /**
+ * Checks whether force mono reception is on or not.
+ * @since S60 3.2
+ * @param aForceMono ETrue if force mono is on, EFalse otherwise.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetForceMonoReception( TBool& aForcedMono ) const;
+
+ /**
+ * Enable or disable quelch.
+ *
+ * @since S60 3.2
+ * @param aEnabled ETrue to enable squelching, EFalse to disable it.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt SetSquelch( TBool aEnabled );
+
+ /**
+ * Retrieves the current squelching (muting in frequencies without reception) setting
+ *
+ * @since S60 3.2
+ * @param aSquelch ETrue if a squelching is currently enabled
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetSquelch( TBool& aSquelch ) const;
+
+//********** PlayerUtility control begins
+
+ /**
+ * Retrieve the current state of the player.
+ * If the radio is already playing, client should simply retrieve current settings such
+ * as volume, etc.
+ *
+ * @since S60 3.2
+ * @return Radio player state.
+ */
+ IMPORT_C TInt PlayerState( TRsPlayerState& aState ) const;
+
+ /**
+ * Starts radio playback.
+ *
+ * @since S60 3.0
+ */
+ IMPORT_C void Play();
+
+ /**
+ * Stops playback, and release the output device for use by other clients.
+ *
+ * @since S60 3.0
+ * @param aIfOnlyPrimaryClient ETrue to stop playback only if there are no other primary clients
+ */
+ IMPORT_C void Stop( TBool aIfOnlyPrimaryClient = EFalse );
+
+ /**
+ * Retrieves the maximum volume supported.
+ *
+ * @since S60 3.0
+ * @param aVolume On return contains the maximum volume.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetMaxVolume( TInt& aMaxVolume ) const;
+
+ /**
+ * Sets the volume to the specified level.
+ *
+ * @since S60 3.0
+ * @param aVolume The volume level to set
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt SetVolume( TInt aVolume );
+
+ /**
+ * Get the current volume.
+ *
+ * @since S60 3.2
+ * @param aVolume On return contains the current volume.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetVolume( TInt& aVolume ) const;
+
+ /**
+ * Set a volume ramp.
+ *
+ * @since S60 3.2
+ * @param aRampInterval The time interval over which the volume should be increased from
+ * zero to the current volume setting.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt SetVolumeRamp( const TTimeIntervalMicroSeconds& aRampInterval );
+
+ /**
+ * Mutes or unmutes playback.
+ *
+ * @since S60 3.0
+ * @param aMute ETrue to mute the audio, EFalse to unmute it.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt Mute( TBool aMute );
+
+ /**
+ * Find out if the audio is muted or not.
+ *
+ * @since S60 3.2
+ * @param aVolume On return set to ETrue if audio is muted.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetMuteStatus( TBool& aMute ) const;
+
+ /**
+ * Set the speaker balance for playing.
+ *
+ * @since S60 3.2
+ * @param aLeftPercentage Left speaker volume percentage. This value ranges from 0 to 100.
+ * @param aRightPercentage Right speaker volume percentage. This value ranges from 0 to 100.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt SetBalance( TInt aLeftPercentage, TInt aRightPercentage );
+
+ /**
+ * Get the current speaker balance setting.
+ *
+ * @since S60 3.2
+ * @param aLeftPercentage On return contains the left speaker volume percentage.
+ * @param aRightPercentage On return contains the right speaker volume percentage.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetBalance( TInt& aLeftPercentage, TInt& aRightPercentage ) const;
+
+//********** RDSUtility control begins
+
+ /**
+ * Get the capabilities of the RDS control on the device.
+ *
+ * @since S60 3.2
+ * @param aCaps The capabilities object to fill
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetRdsCapabilities( TRsRdsCapabilities& aCaps ) const;
+
+ /**
+ * Get the status of the RDS reception.
+ *
+ * @since S60 3.2
+ * @param aRdsSignal On return, will be ETrue if RDS signal can be recepted, EFalse otherwise.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetRdsSignalStatus( TBool& aRdsSignal ) const;
+
+ /**
+ * Subscribe for notification for the specified RDS data. Client should first check
+ * the capabilities to see if a feature is supported.
+ * Request for notification for non-supported features will simply be ignored.
+ *
+ * @since S60 3.2
+ * @param aRdsData Bitfield indicating notification request.
+ * @return A standard system/RadioServer error code.
+ * @see MRadioObserver::RadioEventRdsDataPI
+ * @see MRadioObserver::RadioEventRdsDataPTY
+ * @see MRadioObserver::RadioEventRdsDataPS
+ * @see MRadioObserver::RadioEventRdsDataRT
+ * @see MRadioObserver::RadioEventRdsDataCT
+ * @see MRadioObserver::RadioEventRdsDataTA
+ */
+ IMPORT_C TInt NotifyRdsDataChange( TRsRdsData aRdsData );
+
+ /**
+ * Cancel NotifyRdsDataChange request.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelNotifyRdsDataChange();
+
+ /**
+ * Subscribe for notification for the specified RadioText+ data. Client should first check
+ * the capabilities to see if RT+ feature is supported.
+ * Returns KErrNotSupported if RT+ is not supported.
+ *
+ * Note that if the client wishes to receive the entire radio text data chunk, client should
+ * subscribe for ERsRdsRadioText using NotifyRdsDataChange instead.
+ *
+ * @since S60 3.2
+ * @param aRtPlusClasses Array of RT+ class to be notified
+ * @return A standard system/RadioServer error code.
+ * @see MRadioObserver::RadioEventRdsDataRTplus
+ */
+ IMPORT_C TInt NotifyRadioTextPlusChange( RArray<TInt>& aRtPlusClasses );
+
+ /**
+ * Cancel NotifyRadioTextPlusChange request.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelNotifyRadioTextPlusChange();
+
+ /**
+ * Turn on/off automatic switching of frequency based on Alternate Frequency.
+ * This will cause RDS device to search for alternate frequency when the signal strength
+ * deteriorates. User should be ready to receive RadioEventRdsSearchBeginAF and
+ * RadioEventRdsSearchEndAF. Automatic switching is off by default.
+ *
+ * @since S60 3.2
+ * @param aAuto ETrue to turn automatic switching on, EFalse to turn it off.
+ * @return A standard system/RadioServer error code.
+ * @see MRadioObserver::RadioEventRdsSearchBeginAF
+ * @see MRadioObserver::RadioEventRdsSearchEndAF
+ */
+ IMPORT_C TInt SetAutomaticSwitching( TBool aAuto );
+
+ /**
+ * Find out whether automatic switching is on or off.
+ *
+ * @since S60 3.2
+ * @param aAuto On return, ETrue indicates that automatic switching is enabled.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetAutomaticSwitching( TBool& aAuto );
+
+ /**
+ * Cancel ongoing search for an Alternate Frequency (AF) with stronger signal.
+ *
+ * Client can issue this request to interrupt the search indicated with
+ * MRadioObserver::RadioEventRdsSearchBeginAF.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelAFSearch();
+
+ /**
+ * Turns on/off automatic switching of frequency based on Traffic Announcement.
+ * This will cause RDS device to search for frequencies broadcasting traffic announcement.
+ * Client will be notified of frequency change though the tuner event.
+ * It's up to the client to return to the previous frequency when the traffic announcement
+ * is finished.
+ *
+ * NOTE: This is only supported in dual tuner configuration since the secondary tuner
+ * needs to perform continuous scanning for frequency broadcasting traffic announcement,
+ * while the primary tuner is used for normal tuner activities.
+ *
+ * @since S60 3.2
+ * @param aAuto ETrue indicates that automatic switching is on.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt SetAutomaticTrafficAnnouncement( TBool aAuto );
+
+ /**
+ * Find out whether automatic traffic announcement is enabled.
+ *
+ * @since S60 3.2
+ * @param aAuto On return, ETrue indicates that automatic traffic announcement is on.
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetAutomaticTrafficAnnouncement( TBool& aAuto );
+
+ /**
+ * Asynchronous request to find a radio station with the specified Programme Type(PTY),
+ * starting from the currently tuned frequency and searching in the direction specified
+ * (i.e. up or down). User must be ready to receive callback method StationSeekByPTYComplete
+ * The station found is returned in the callback.
+ *
+ * @since S60 3.2
+ * @param aPty The type of programme to search for.
+ * @param aSeekUp The direction to search in. Searches upwards if set to ETrue.
+ * @see MRadioObserver::StationSeekByPTYComplete
+ */
+ IMPORT_C void StationSeekByPTY( TRsRdsProgrammeType aPty, TBool aSeekUp );
+
+ /**
+ * Asynchronous request to find a radio station with Traffic Announcement(TA),
+ * starting from the currently tuned frequency and searching in the direction specified
+ * (i.e. up or down). User must be ready to receive callback method StationSeekByTAComplete
+ * The station found is returned in the callback.
+ *
+ * @since S60 3.2
+ * @param aSeekUp The direction to search in. Searches upwards if set to ETrue.
+ * @see MRadioObserver::StationSeekByTAComplete
+ */
+ IMPORT_C void StationSeekByTA( TBool aSeekUp );
+
+ /**
+ * Asynchronous request to find a radio station with Traffic Programme(TP),
+ * starting from the currently tuned frequency and searching in the direction specified
+ * (i.e. up or down). User must be ready to receive callback method StationSeekByTPComplete
+ * The station found is returned in the callback.
+ *
+ * @since S60 3.2
+ * @param aSeekUp The direction to search in. Searches upwards if set to ETrue.
+ * @see MRadioObserver::StationSeekByTPComplete
+ */
+ IMPORT_C void StationSeekByTP( TBool aSeekUp );
+
+ /**
+ * Cancels an ongoing retune operation, as initiated by a call to StationSeekByPTY,
+ * StationSeekByTA, or StationSeekByTP.
+ * The usual callback will not occur if this has been called.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelRdsStationSeek();
+
+ /**
+ * Asynchronous request to find all frequencies sending the given Programme Type (PTY).
+ * User must be ready to receive callback method GetFreqByPTYComplete.
+ *
+ * NOTE: This is only supported in dual tuner configuration since the secondary tuner
+ * needs to perform continuous scanning for frequencies broadcasting given Programme Type
+ * while the primary tuner is used for normal tuner activities.
+ * Client should first check the tuner capabilities. Will return KErrNotSupported in
+ * callback method if this feature is not supported.
+ *
+ * @since S60 3.2
+ * @param aPty The type of programme to search for
+ * @see MRadioObserver::GetFreqByPTYComplete
+ */
+ IMPORT_C void GetFreqByPTY( TRsRdsProgrammeType aPty );
+
+ /**
+ * Cancels an ongoing request to find all frequencies sending a given Programme Type (PTY).
+ * The usual callback will not occur if this has been called.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelGetFreqByPTY();
+
+ /**
+ * Asynchronous request to find all frequencies sending Traffic Announcement (TA). User must
+ * be ready to receive callback method GetFreqByTAComplete.
+ *
+ * NOTE: This is only supported in dual tuner configuration since the secondary tuner
+ * needs to perform continuous scanning for frequencies broadcasting given Traffic Announcement
+ * while the primary tuner is used for normal tuner activities.
+ * Client should first check the tuner capabilities. Will return KErrNotSupported in
+ * callback method if this feature is not supported.
+ *
+ * @since S60 3.2
+ * @see MRadioObserver::GetFreqByTAComplete
+ */
+ IMPORT_C void GetFreqByTA();
+
+ /**
+ * Cancels an ongoing request to find all frequencies sending Traffic Announcement.
+ * The usual callback will not occur if this has been called.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelGetFreqByTA();
+
+ /**
+ * Asynchronous request to find all Programme Service names (PS) sending the given Programme
+ * Type (PTY). User must be ready to receive callback method GetPSByPTYComplete.
+ *
+ * NOTE: This is only supported in dual tuner configuration since the secondary tuner
+ * needs to perform continuous scanning for frequencies broadcasting given Programme Type
+ * while the primary tuner is used for normal tuner activities.
+ * Client should first check the tuner capabilities. Will return KErrNotSupported in
+ * callback method if this feature is not supported.
+ *
+ * @since S60 3.2
+ * @param aPty The type of programme to search for
+ * @see MRadioObserver::GetPSByPTYComplete
+ */
+ IMPORT_C void GetPSByPTY( TRsRdsProgrammeType aPty );
+
+ /**
+ * Cancels an ongoing request to find all Programme Service names (PS) sending a given
+ * Programme Type (PTY). The usual callback will not occur if this has been called.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelGetPSByPTY();
+
+ /**
+ * Asynchronous request to find all Programme Service names (PS) sending Traffic Announcement (TA).
+ * User must be ready to receive callback method GetPSByTAComplete.
+ *
+ * NOTE: This is only supported in dual tuner configuration since the secondary tuner
+ * needs to perform continuous scanning for frequencies broadcasting given Traffic Announcement
+ * while the primary tuner is used for normal tuner activities.
+ * Client should first check the tuner capabilities. Will return KErrNotSupported in
+ * callback method if this feature is not supported.
+ *
+ * @since S60 3.2
+ * @see MRadioObserver::GetPSByTAComplete
+ */
+ IMPORT_C void GetPSByTA();
+
+ /**
+ * Cancels an ongoing request to find all Programme Service names (PS) sending Traffic Announcement.
+ * The usual callback will not occur if this has been called.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelGetPSByTA();
+
+ /**
+ * Get the current Programme Identification code.
+ * RDS data is received over the air and may not be available immediately following
+ * tune operation. If data is not available, this function will return KErrNotFound.
+ * If a value is returned, this is the last known value, which may not be up to date.
+ * To be notified of the most recent value, client should use NotifyRdsDataChange.
+ *
+ * @since S60 3.2
+ * @param aPi On return contains Programme Identification code
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetProgrammeIdentification( TInt& aPi );
+
+ /**
+ * Get the current Programme Type.
+ * RDS data is received over the air and may not be available immediately following
+ * tune operation. If data is not available, this function will return KErrNotFound.
+ * If a value is returned, this is the last known value, which may not be up to date.
+ * To be notified of the most recent value, client should use NotifyRdsDataChange.
+ *
+ * @since S60 3.2
+ * @param aPty On return contains Programme Type
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetProgrammeType( TRsRdsProgrammeType& aPty );
+
+ /**
+ * Get the current Programme Service name.
+ * RDS data is received over the air and may not be available immediately following
+ * tune operation. If data is not available, this function will return KErrNotFound.
+ * If a value is returned, this is the last known value, which may not be up to date.
+ * To be notified of the most recent value, client should use NotifyRdsDataChange.
+ *
+ * Programme Service name is fixed to 8 characters.
+ *
+ * @since S60 3.2
+ * @param aPs On return contains Programme Service name
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetProgrammeService( TRsRdsPSName& aPs );
+
+ /**
+ * Get the current Radio Text.
+ * RDS data is received over the air and may not be available immediately following
+ * tune operation. If data is not available, this function will return KErrNotFound.
+ * If a value is returned, this is the last known value, which may not be up to date.
+ * To be notified of the most recent value, client should use NotifyRdsDataChange.
+ *
+ * The maximum possible length for radio text field is 64 characters.
+ *
+ * @since S60 3.2
+ * @param aRt On return contains Radio Text
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetRadioText( TRsRdsRadioText& aRt );
+
+ /**
+ * Get the current Radio Text+.
+ * RDS data is received over the air and may not be available immediately following
+ * tune operation. If data is not available, this function will return KErrNotFound.
+ * If a value is returned, this is the last known value, which may not be up to date.
+ * To be notified of the most recent value, client should use NotifyRdsDataChange.
+ *
+ * The maximum possible length for radio text+ field is 64 characters.
+ *
+ * @since S60 3.2
+ * @param aRtPlusClass Radio text plus class
+ * @param aRtPlusData On return contains Radio Text+ field
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetRadioTextPlus( TRsRdsRTplusClass aRtPlusClass, TRsRdsRadioText& aRtPlusData );
+
+ /**
+ * Get the current Clock Time and date.
+ * RDS data is received over the air and may not be available immediately following
+ * tune operation. If data is not available, this function will return KErrNotFound.
+ * If a value is returned, this is the last known value, which may not be up to date.
+ * To be notified of the most recent value, client should use NotifyRdsDataChange.
+ *
+ * @since S60 3.2
+ * @param aCt On return contains current time and date
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetClockTime( TDateTime& aCt );
+
+ /**
+ * Get Traffic Announcement status at the current station.
+ *
+ * @since S60 3.2
+ * @param aTaStatus On return, will be ETrue if current station has ongoing traffic announcement
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetTrafficAnnouncementStatus( TBool& aTaStatus );
+
+ /**
+ * Get Traffic Programme status at the current station.
+ *
+ * @since S60 3.2
+ * @param aTpStatus On return, will be ETrue if current station supports traffic programme
+ * @return A standard system/RadioServer error code.
+ */
+ IMPORT_C TInt GetTrafficProgrammeStatus( TBool& aTpStatus );
+
+// from base class MCustomCommand
+
+ /**
+ * From MCustomCommand
+ * Sends a synchronous custom command to the radio server.
+ *
+ * @since S60 3.0
+ * @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 );
+
+ /**
+ * From MCustomCommand
+ * Sends a synchronous custom command to the radio server.
+ *
+ * @since S60 3.0
+ * @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 );
+
+ /**
+ * From MCustomCommand
+ * Sends an asynchronous custom command to the radio server.
+ *
+ * @since S60 3.0
+ * @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 );
+
+ /**
+ * From MCustomCommand
+ * Sends an asynchronous custom command to the radio server.
+ *
+ * @since S60 3.0
+ * @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 );
+
+//********** Internal functions begin
+
+ /**
+ * Used internally to cancel outstanding asynchronous requests. This is triggered by
+ * CRadioRequest.
+ *
+ * @since S60 3.0
+ * @param aRequest The outstanding asynchronous request being cancelled
+ */
+ void CancelRequest( TInt aRequest );
+
+private:
+
+ /**
+ * Creates request handlers for each asynchronous request.
+ */
+ void StartRequestHandlersL( MRadioObserver& aObserver );
+
+ /**
+ * Creates event handlers for tuner and playback events from radio tuner.
+ */
+ void StartEventHandlersL( MRadioObserver& aObserver );
+
+ /**
+ * Creates event handlers for RDS events from radio tuner.
+ */
+ void StartRdsEventHandlersL( TUint32 aRdsFunctions );
+
+private: // Data
+
+ // Connection status
+ TBool iConnected;
+ // Requests that generates response to MRadioObserver
+ RPointerArray<CRadioRequest> iRequests;
+ // Event handlers that generates response to MRadioEventObserver
+ RPointerArray<CRadioEventHandler> iEventHandlers;
+ //Rds Event handlers
+ RPointerArray<CRadioEventHandler> iRdsEventHandlers;
+
+ // Destination information for standard radio interface messages
+ TMMFMessageDestinationPckg iDestinationPckg;
+
+ // Radio observer
+ MRadioObserver* iObserver;
+ // Client type
+ TBool iPrimaryClient;
+ // RDS notify flag
+ TBool iRdsNotify;
+ };
+
+#endif // RADIOSESSION_H
+
+// End of File