1 /*

     2 * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This class is the main interface to the RadioServer. It implements

    15 *				 the client-side session. It also contains M-observer classes that

    16 *				 the client must implement to receive completion notification for

    17 *				 asynchronous requests and spontaneous event notifications.

    18 *

    19 */

    20 

    21 

    22 

    23 #ifndef RADIOSESSION_H

    24 #define RADIOSESSION_H

    25 

    26 //  INCLUDES

    27 #include <mmf/common/mmfbase.h>

    28 #include <mmf/common/mmfcontrollerframework.h>

    29 #include <MCustomCommand.h>

    30 

    31 #include "RadioServerData.h"

    32 #include "RadioStubManager.h"

    33 

    34 // FORWARD DECLARATIONS

    35 class CRadioRequest;

    36 class CRadioEventHandler;

    37 

    38 // CLASS DECLARATION

    39 

    40 /**

    41 *  Defines functions that client must implement in order to receive

    42 *  events from the radio server.

    43 *

    44 *  @lib RadioSession.lib

    45 *  @since S60 3.0

    46 */

    47 class MRadioObserver

    48     {

    49 public: // New functions

    50 

    51 //********** Tuner related

    52 

    53 	/**

    54      * Completion message for RequestTunerControl request.

    55      *

    56      * @since S60 3.2

    57      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

    58      */

    59 	virtual void RequestTunerControlComplete( TRadioServerError aError ) = 0;

    60 

    61 	/**

    62      * Completion message for SetFrequencyRange request.

    63      *

    64      * @since S60 3.2

    65      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

    66      */

    67 	virtual void SetFrequencyRangeComplete( TRadioServerError aError ) = 0;

    68 

    69 	/**

    70      * Completion message for SetFrequency request.

    71      *

    72      * @since S60 3.0

    73      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

    74      */

    75 	virtual void SetFrequencyComplete( TRadioServerError aError ) = 0;

    76 

    77 	/**

    78      * Completion message for StationSeek request.

    79      *

    80      * @since S60 3.0

    81      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

    82      * @param aFrequency Valid only if aError is KErrNone. Contains the new frequency in Hz.

    83      */

    84 	virtual void StationSeekComplete( TRadioServerError aError, TInt aFrequency ) = 0;

    85 

    86 	/**

    87      * Event notification indicating FM transmitter status change. Radio receiver

    88      * is turned off when FM transmitter is active.

    89      *

    90      * @since S60 3.2

    91      * @param aActive ETrue if FM transmitter is active; EFalse otherwise.

    92      */

    93 	virtual void RadioEventTransmitterStatusChange( TBool aActive ) = 0;

    94 

    95 	/**

    96      * Event notification indicating antenna status change.

    97      *

    98      * @since S60 3.0

    99      * @param aAttached ETrue if antenna is attached.

   100      */

   101 	virtual void RadioEventAntennaStatusChange( TBool aAttached ) = 0;

   102 

   103 	/**

   104      * Event notification indicating offline mode change.

   105      *

   106      * @since S60 3.0

   107      * @param aOfflineMode ETrue if device is in offline mode.

   108      */

   109 	virtual void RadioEventOfflineModeChange( TBool aOfflineMode ) = 0;

   110 

   111 	/**

   112      * Event notification indicating frequency range change. This may be caused by

   113      * other applications.

   114      *

   115      * @since S60 3.2

   116      * @param aNewRange New frequency range.

   117      */

   118 	virtual void RadioEventFrequencyRangeChanged( TRsFrequencyRange aNewRange ) = 0;

   119 

   120 	/**

   121      * Event notification indicating frequency(Hz) change. This may be caused by

   122      * other applications or RDS if AF/TA is enabled.

   123      *

   124      * @since S60 3.2

   125      * @param aFrequency New frequency where tuner is currently tuned.

   126      */

   127 	virtual void RadioEventFrequencyChange( TInt aFrequency ) = 0;

   128 

   129 	/**

   130      * Event notification indicating forced mono status change.

   131      *

   132      * @since S60 3.2

   133      * @param aForcedMono ETrue if forced mode is enabled; EFalse otherwise.

   134      */

   135 	virtual void RadioEventForcedMonoChanged( TBool aForcedMono ) = 0;

   136 

   137 	/**

   138      * Event notification indicating squelch (muting the frequencies without broadcast) status change.

   139      *

   140      * @since S60 3.2

   141      * @param aSquelch ETrue if squelch is enabled; EFalse otherwise.

   142      */

   143 	virtual void RadioEventSquelchChanged( TBool aSquelch ) = 0;

   144 

   145 //********** Player related

   146 

   147 	/**

   148      * Event notification indicating radio player state change. This may be caused by

   149      * other applications.

   150      *

   151      * @since S60 3.0

   152      * @param aRadioOn ETrue if radio is playing, otherwise radio is off.

   153      * @param aError Valid only if aRadioOn is EFalse. Contains the reason why radio is off.

   154      */

   155 	virtual void RadioEventStateChange( TBool aRadioOn, TRadioServerError aError ) = 0;

   156 

   157 	/**

   158      * Event notification indicating volume change.

   159      *

   160      * @since S60 3.2

   161      * @param aVolume New volume.

   162      */

   163 	virtual void RadioEventVolumeChange( TInt aVolume ) = 0;

   164 

   165 	/**

   166      * Event notification indicating mute setting change.

   167      *

   168      * @since S60 3.2

   169      * @param aMute ETrue indicates audio is muted.

   170      */

   171 	virtual void RadioEventMuteChange( TBool aMute ) = 0;

   172 

   173 	/**

   174      * Event notification indicating balance setting change.

   175      *

   176      * @since S60 3.2

   177      * @param aLeftPercentage Left speaker volume percentage. This value ranges from 0 to 100.

   178      * @param aRightPercentage Right speaker volume percentage. This value ranges from 0 to 100.

   179      */

   180 	virtual void RadioEventBalanceChange( TInt aLeftPercentage, TInt aRightPercentage ) = 0;

   181 

   182 //********** RDS related

   183 

   184 	/**

   185      * Completion message for StationSeekByPTY request.

   186      *

   187      * @since S60 3.2

   188      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

   189      * @param aFrequency The frequency(Hz) of the radio station that was found.

   190      */

   191 	virtual void StationSeekByPTYComplete( TRadioServerError aError, TInt aFrequency ) = 0;

   192 

   193 	/**

   194      * Completion message for StationSeekByTA request.

   195      *

   196      * @since S60 3.2

   197      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

   198      * @param aFrequency The frequency(Hz) of the radio station that was found.

   199      */

   200 	virtual void StationSeekByTAComplete( TRadioServerError aError, TInt aFrequency ) = 0;

   201 

   202 	/**

   203      * Completion message for StationSeekByTP request.

   204      *

   205      * @since S60 3.2

   206      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

   207      * @param aFrequency The frequency(Hz) of the radio station that was found.

   208      */

   209 	virtual void StationSeekByTPComplete( TRadioServerError aError, TInt aFrequency ) = 0;

   210 

   211 	/**

   212      * Completion message for GetFreqByPTY request.

   213      *

   214      * @since S60 3.2

   215      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

   216      * @param aFreqList Array of frequencies (Hz), valid only if aError is KErrNone.

   217      */

   218 	virtual void GetFreqByPTYComplete( TRadioServerError aError, RArray<TInt>& aFreqList ) = 0;

   219 

   220 	/**

   221      * Completion message for GetFreqByTA request.

   222      *

   223      * @since S60 3.2

   224      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

   225      * @param aFreqList Array of frequencies (Hz), valid only if aError is KErrNone.

   226      */

   227 	virtual void GetFreqByTAComplete( TRadioServerError aError, RArray<TInt>& aFreqList ) = 0;

   228 

   229 	/**

   230      * Completion message for StatGetPSByPTY request.

   231      *

   232      * @since S60 3.2

   233      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

   234      * @param aPsList Array of programme service names, valid only if aError is KErrNone.

   235      */

   236 	virtual void GetPSByPTYComplete( TRadioServerError aError, RArray<TRsRdsPSName>& aPsList ) = 0;

   237 

   238 	/**

   239      * Completion message for GetPSByTA request.

   240      *

   241      * @since S60 3.2

   242      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

   243      * @param aPsList Array of programme service names, valid only if aError is KErrNone.

   244      */

   245 	virtual void GetPSByTAComplete( TRadioServerError aError, RArray<TRsRdsPSName>& aPsList ) = 0;

   246 

   247 	/**

   248      * Event notification indicating new Programme Identification(PI) is available.

   249      *

   250      * @since S60 3.2

   251      * @param aPi Programme identification

   252      */

   253 	virtual void RadioEventRdsDataPI( TInt aPi ) = 0;

   254 

   255 	/**

   256      * Event notification indicating new Programme Type(PTY) is available.

   257      *

   258      * @since S60 3.2

   259      * @param aPty Programme type

   260      */

   261 	virtual void RadioEventRdsDataPTY( TRsRdsProgrammeType aPty ) = 0;

   262 

   263 	/**

   264      * Event notification indicating new Programme Service(PS) is available.

   265      *

   266      * @since S60 3.2

   267      * @param aPs Programme service

   268      */

   269 	virtual void RadioEventRdsDataPS( TRsRdsPSName& aPs ) = 0;

   270 

   271 	/**

   272      * Event notification indicating new Radio Text(RT) is available.

   273      *

   274      * @since S60 3.2

   275      * @param aRt Radio text

   276      */

   277 	virtual void RadioEventRdsDataRT( TRsRdsRadioText& aRt ) = 0;

   278 

   279 	/**

   280      * Event notification indicating new Clock Time(CT) is available.

   281      *

   282      * @since S60 3.2

   283      * @param aCt Clock time

   284      */

   285 	virtual void RadioEventRdsDataCT( TDateTime& aCt ) = 0;

   286 

   287 	/**

   288      * Event notification indicating Traffice Announcement(TA) status change.

   289      *

   290      * @since S60 3.2

   291      * @param aTaOn ETrue indicates that Traffic Announcement is on.

   292      */

   293 	virtual void RadioEventRdsDataTA( TBool aTaOn ) = 0;

   294 

   295 	/**

   296      * Event notification indicating new Radio Text+(RT+) is available.

   297      *

   298      * @since S60 3.2

   299 	 * @param aRtPlusClass Radio text plus class

   300 	 * @param aRtPlusData Radio text plus data

   301 	 */

   302 	virtual void RadioEventRdsDataRTplus( TRsRdsRTplusClass aRtPlusClass, TRsRdsRadioText& aRtPlusData ) = 0;

   303 

   304 	/**

   305      * Event notification indicating the beginning of Alternate Frequency(AF) search.

   306      *

   307      * @since S60 3.2

   308      */

   309 	virtual void RadioEventRdsSearchBeginAF() = 0;

   310 

   311 	/**

   312      * Event notification indicating the end of Alternate Frequency(AF) search.

   313      *

   314      * @since S60 3.2

   315      * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

   316      * @param aFrequency The frequency(Hz) of the radio station that was found.

   317      */

   318 	virtual void RadioEventRdsSearchEndAF( TRadioServerError aError, TInt aFrequency ) = 0;

   319 

   320 	/**

   321      * Event notification indicating station change to another frequency(Hz) that is

   322      * broadcasting Traffic Announcement(TA).

   323      *

   324      * @since S60 3.2

   325      * @param aFrequency The frequency(Hz) of the radio station that was found.

   326      */

   327 	virtual void RadioEventRdsStationChangeTA( TInt aFrequency ) = 0;

   328 

   329 	/**

   330      * Event notification indicating automatic switching (AF) setting change.

   331      *

   332      * @since S60 3.2

   333      * @param aAuto ETrue indicates that automatic switching is on.

   334      */

   335 	virtual void RadioEventRdsAutomaticSwitchingChange( TBool aAuto ) = 0;

   336 

   337 	/**

   338      * Event notification indicating automatic traffic announcement setting change.

   339      *

   340      * @since S60 3.2

   341      * @param aAuto ETrue indicates that automatic traffic announcement is on.

   342      */

   343 	virtual void RadioEventRdsAutomaticTrafficAnnouncement( TBool aAuto ) = 0;

   344 

   345 	/**

   346      * Event notification indicating RDS signal status change (i.e. signal is lost/restored).

   347      *

   348      * @since S60 3.2

   349      * @param aSignal ETrue indicates that RDS signal is available in the tuned frequency.

   350      */

   351 	virtual void RadioEventRdsSignalChange( TBool aSignal ) = 0;

   352     };

   353 

   354 /**

   355 *  Main interface to the Radio Server.

   356 *  Implements the client-side session.

   357 *

   358 *  @lib RadioSession.lib

   359 *  @since S60 3.0

   360 */

   361 class RRadioSession : public RSessionBase,

   362 					  public MCustomCommand

   363     {

   364 public: // New functions

   365     IMPORT_C static RRadioSession* NewL();

   366     

   367 public:  // Constructors and destructor

   368 

   369 	/**

   370      * C++ default constructor.

   371      */

   372 	IMPORT_C RRadioSession();

   373 

   374 public: // New functions

   375 

   376     /**

   377      * Connects a client to the radio server.

   378      * @since S60 3.0

   379      *

   380      * @param aObserver The observer object for receiving async completion callbacks.

   381      * @param aPrimaryClient Indicates whether the client is a primary client. Primary

   382      * clients are clients that can control the radio tuner such as FM Radio Application,

   383      * Visual Radio, or a Java Radio App.  Non-primary clients are observers of the tuner,

   384      * player, and RDS utilities and cannot exist without a primary client such as Active

   385      * Idle, Cover UI, or a smart accessory driver.

   386      * @return A standard system error code.

   387      */

   388 	IMPORT_C TInt Connect( MRadioObserver& aObserver, TBool aPrimaryClient );

   389 

   390 	/**

   391      * Gets the client side version number.

   392      *

   393      * @since S60 3.0

   394      * @return The client side version number.

   395      */

   396 	IMPORT_C TVersion Version() const;

   397 

   398 	/**

   399      * Closes connection to the radio server.

   400      *

   401      * @since S60 3.0

   402      */

   403 	IMPORT_C void Close();

   404 

   405 //********** TunerUtility control begins

   406 

   407 	/**

   408      * Request for control of a tuner. If this method returns KErrNone, control of

   409      * the tuner has been granted. Control to the tuner must be granted before any

   410      * other request can be made.

   411      *

   412      * @since S60 3.2

   413      * @param Tuner type (e.g. FM, AM)

   414      * @return A standard system error code.

   415      * @see MRadioObserver::RequestTunerControlComplete

   416      */

   417 	IMPORT_C void RequestTunerControl( TRsTuner aTuner );

   418 

   419 	/**

   420      * Get the capabilities of the radio on the device.

   421      *

   422      * @since S60 3.2

   423      * @param aCaps The capabilities object to fill

   424      * @return A standard system error code.

   425      */

   426 	IMPORT_C TInt GetTunerCapabilities( TRsTunerCapabilities& aCaps ) const;

   427 

   428 	/**

   429      * EnableTunerInOfflineMode on the device.

   430      *

   431      * @since S60 3.2

   432      * @param aEnable ETrue to enable tuner functions in offline mode, EFalse to disable.

   433      * @return A standard system/RadioServer error code.

   434      */

   435 	IMPORT_C TInt EnableTunerInOfflineMode( TBool aEnable );

   436 

   437 	/**

   438      * Asynchronous request to set the frequency range. If the frequency range is not set,

   439      * it will be defaulted to ERsTunerFM.

   440      *

   441      * @since S60 3.2

   442      * @param aRange Frequency range

   443      * @see MRadioObserver::SetFrequencyRangeComplete

   444      */

   445 	IMPORT_C void SetFrequencyRange( TRsFrequencyRange aRange );

   446 

   447 	/**

   448      * Cancels an outstanding SetFrequencyRange request. Note that SetFrequencyRange may

   449      * complete before cancel can occur and a callback may occur.

   450      *

   451      * @since S60 3.2

   452      * @return A standard system error code.

   453      */

   454 	IMPORT_C void CancelSetFrequencyRange();

   455 

   456 	/**

   457      * Get the current frequency range. It also returns the minimum and maximum frequencies(Hz)

   458      * for the returned range.

   459      *

   460      * @since S60 3.2

   461      * @param aRange On return contains the current frequency range.

   462      * @param aMinFreq On return contains the minimum frequency for the current frequency range.

   463      * @param aMaxFreq On return contains the maximum frequency for the current frequency range.

   464      * @return A standard system/RadioServer error code.

   465      */

   466 	IMPORT_C TInt GetFrequencyRange( TRsFrequencyRange& aRange, TInt& aMinFreq, TInt& aMaxFreq ) const;

   467 

   468 	/**

   469      * Asynchronous request to tune the tuner to the specified frequency.

   470      *

   471      * @since S60 3.2

   472      * @param aFrequency The frequency (Hz) to tune to

   473      * @see MRadioObserver::SetFrequecyComplete

   474      */

   475 	IMPORT_C void SetFrequency( TInt aFrequency );

   476 

   477 	/**

   478      * Cancels an outstanding SetFrequency request. Note that SetFrequency may complete before

   479      * cancel can occur and a callback to MRadioObserver::SetFrequencyComplete may occur.

   480      *

   481      * @since S60 3.0

   482      * @return A standard system/RadioServer error code.

   483      */

   484 	IMPORT_C void CancelSetFrequency();

   485 

   486 	/**

   487      * Get the current frequency.

   488      *

   489      * @since S60 3.2

   490      * @param aFrequency On return contains the current frequency(Hz).

   491      * @return A standard system/RadioServer error code.

   492      */

   493 	IMPORT_C TInt GetFrequency( TInt& aFrequency ) const;

   494 

   495 	/**

   496      * Asynchronous request to find a radio station, starting from current frequency and

   497      * seaching in the direction specified (i.e. up or down).

   498      *

   499      * @since S60 3.0

   500      * @param aSeekUp Search direction

   501      * @see MRadioObserver::StationSeekComplete

   502      */

   503 	IMPORT_C void StationSeek( TBool aUpwards );

   504 

   505 	/**

   506      * Cancels an outstanding StationSeek request. Note that StationSeek may complete before

   507      * cancel can occur and a callback to MRadioObserver::StationSeekComplete may occur.

   508      *

   509      * @since S60 3.0

   510      * @return A standard system/RadioServer error code.

   511      */

   512 	IMPORT_C void CancelStationSeek();

   513 

   514 	/**

   515      * Gets the signal strength of the currently tuned signal.

   516      *

   517      * @since S60 3.2

   518      * @param aStrength On return contains the current signal strength.

   519      * @return A standard system/RadioServer error code.

   520      */

   521 	IMPORT_C TInt GetSignalStrength( TInt& aSignalStrength ) const;

   522 

   523 	/**

   524      * Gets the maximum possible signal strength of a tuned signal.

   525      *

   526      * @since S60 3.2

   527      * @param aMaxStrength On return contains the maximum signal strength.

   528      * @return A standard system/RadioServer error code.

   529      */

   530 	IMPORT_C TInt GetMaxSignalStrength( TInt& aMaxSignalStrength ) const;

   531 

   532 	/**

   533      * Get the stereo mode of the radio.

   534      *

   535      * @since S60 3.2

   536      * @param aStereo On return, will be ETrue if signal is stereo.

   537      * @return A standard system/RadioServer error code.

   538      */

   539 	IMPORT_C TInt GetStereoMode( TBool& aStereo ) const;

   540 

   541 	/**

   542      * Indicates whether the reception should be forced into monophonic mode.

   543      *

   544      * @since S60 3.2

   545      * @param aMono If ETrue, all reception will be in mono mode even if a stereo signal is

   546      *		 available. If EFalse, a stereo signal will be received when possible.

   547      * @return A standard system/RadioServer error code.

   548      */

   549 	IMPORT_C TInt ForceMonoReception( TBool aForcedMono );

   550 

   551 	/**

   552      * Checks whether force mono reception is on or not.

   553      * @since S60 3.2

   554      * @param aForceMono ETrue if force mono is on, EFalse otherwise.

   555      * @return A standard system/RadioServer error code.

   556      */

   557 	IMPORT_C TInt GetForceMonoReception( TBool& aForcedMono ) const;

   558 

   559 	/**

   560      * Enable or disable quelch.

   561      *

   562      * @since S60 3.2

   563      * @param aEnabled ETrue to enable squelching, EFalse to disable it.

   564      * @return A standard system/RadioServer error code.

   565      */

   566 	IMPORT_C TInt SetSquelch( TBool aEnabled );

   567 

   568 	/**

   569 	 * Retrieves the current squelching (muting in frequencies without reception) setting

   570      *

   571      * @since S60 3.2

   572      * @param aSquelch ETrue if a squelching is currently enabled

   573      * @return A standard system/RadioServer error code.

   574      */

   575 	IMPORT_C TInt GetSquelch( TBool& aSquelch ) const;

   576 

   577 //********** PlayerUtility control begins

   578 

   579 	/**

   580      * Retrieve the current state of the player.

   581 	 * If the radio is already playing, client should simply retrieve current settings such

   582      * as volume, etc.

   583      *

   584      * @since S60 3.2

   585      * @return Radio player state.

   586      */

   587 	IMPORT_C TInt PlayerState( TRsPlayerState& aState ) const;

   588 

   589 	/**

   590      * Starts radio playback.

   591      *

   592      * @since S60 3.0

   593      */

   594 	IMPORT_C void Play();

   595 

   596 	/**

   597      * Stops playback, and release the output device for use by other clients.

   598      *

   599      * @since S60 3.0

   600      * @param aIfOnlyPrimaryClient ETrue to stop playback only if there are no other primary clients

   601      */

   602 	IMPORT_C void Stop( TBool aIfOnlyPrimaryClient = EFalse );

   603 

   604 	/**

   605      * Retrieves the maximum volume supported.

   606      *

   607      * @since S60 3.0

   608      * @param aVolume On return contains the maximum volume.

   609      * @return A standard system/RadioServer error code.

   610      */

   611 	IMPORT_C TInt GetMaxVolume( TInt& aMaxVolume ) const;

   612 

   613 	/**

   614      * Sets the volume to the specified level.

   615      *

   616      * @since S60 3.0

   617      * @param aVolume The volume level to set

   618      * @return A standard system/RadioServer error code.

   619      */

   620 	IMPORT_C TInt SetVolume( TInt aVolume );

   621 

   622 	/**

   623      * Get the current volume.

   624      *

   625      * @since S60 3.2

   626      * @param aVolume On return contains the current volume.

   627      * @return A standard system/RadioServer error code.

   628      */

   629 	IMPORT_C TInt GetVolume( TInt& aVolume ) const;

   630 

   631 	/**

   632      * Set a volume ramp.

   633      *

   634      * @since S60 3.2

   635      * @param aRampInterval The time interval over which the volume should be increased from

   636      *		 zero to the current volume setting.

   637      * @return A standard system/RadioServer error code.

   638      */

   639 	IMPORT_C TInt SetVolumeRamp( const TTimeIntervalMicroSeconds& aRampInterval );

   640 

   641 	/**

   642      * Mutes or unmutes playback.

   643      *

   644      * @since S60 3.0

   645      * @param aMute ETrue to mute the audio, EFalse to unmute it.

   646      * @return A standard system/RadioServer error code.

   647      */

   648 	IMPORT_C TInt Mute( TBool aMute );

   649 

   650 	/**

   651      * Find out if the audio is muted or not.

   652      *

   653      * @since S60 3.2

   654      * @param aVolume On return set to ETrue if audio is muted.

   655      * @return A standard system/RadioServer error code.

   656      */

   657 	IMPORT_C TInt GetMuteStatus( TBool& aMute ) const;

   658 

   659 	/**

   660      * Set the speaker balance for playing.

   661      *

   662      * @since S60 3.2

   663      * @param aLeftPercentage Left speaker volume percentage. This value ranges from 0 to 100.

   664      * @param aRightPercentage Right speaker volume percentage. This value ranges from 0 to 100.

   665      * @return A standard system/RadioServer error code.

   666      */

   667 	IMPORT_C TInt SetBalance( TInt aLeftPercentage, TInt aRightPercentage );

   668 

   669 	/**

   670      * Get the current speaker balance setting.

   671      *

   672      * @since S60 3.2

   673      * @param aLeftPercentage On return contains the left speaker volume percentage.

   674      * @param aRightPercentage On return contains the right speaker volume percentage.

   675      * @return A standard system/RadioServer error code.

   676      */

   677 	IMPORT_C TInt GetBalance( TInt& aLeftPercentage, TInt& aRightPercentage ) const;

   678 

   679 //********** RDSUtility control begins

   680 

   681 	/**

   682      * Get the capabilities of the RDS control on the device.

   683      *

   684      * @since S60 3.2

   685      * @param aCaps The capabilities object to fill

   686      * @return A standard system/RadioServer error code.

   687      */

   688 	IMPORT_C TInt GetRdsCapabilities( TRsRdsCapabilities& aCaps ) const;

   689 

   690 	/**

   691      * Get the status of the RDS reception.

   692      *

   693      * @since S60 3.2

   694      * @param aRdsSignal On return, will be ETrue if RDS signal can be recepted, EFalse otherwise.

   695      * @return A standard system/RadioServer error code.

   696      */

   697 	IMPORT_C TInt GetRdsSignalStatus( TBool& aRdsSignal ) const;

   698 

   699 	/**

   700      * Subscribe for notification for the specified RDS data. Client should first check

   701      * the capabilities to see if a feature is supported.

   702      * Request for notification for non-supported features will simply be ignored.

   703      *

   704      * @since S60 3.2

   705      * @param aRdsData Bitfield indicating notification request.

   706      * @return A standard system/RadioServer error code.

   707      * @see MRadioObserver::RadioEventRdsDataPI

   708      * @see MRadioObserver::RadioEventRdsDataPTY

   709      * @see MRadioObserver::RadioEventRdsDataPS

   710      * @see MRadioObserver::RadioEventRdsDataRT

   711      * @see MRadioObserver::RadioEventRdsDataCT

   712      * @see MRadioObserver::RadioEventRdsDataTA

   713      */

   714 	IMPORT_C TInt NotifyRdsDataChange( TRsRdsData aRdsData );

   715 

   716 	/**

   717      * Cancel NotifyRdsDataChange request.

   718      *

   719      * @since S60 3.2

   720      */

   721 	IMPORT_C void CancelNotifyRdsDataChange();

   722 

   723     /**

   724      * Subscribe for notification for the specified RadioText+ data. Client should first check

   725      * the capabilities to see if RT+ feature is supported.

   726      * Returns KErrNotSupported if RT+ is not supported.

   727      *

   728      * Note that if the client wishes to receive the entire radio text data chunk, client should

   729      * subscribe for ERsRdsRadioText using NotifyRdsDataChange instead.

   730      *

   731      * @since S60 3.2

   732      * @param aRtPlusClasses Array of RT+ class to be notified

   733      * @return A standard system/RadioServer error code.

   734      * @see MRadioObserver::RadioEventRdsDataRTplus

   735      */

   736     IMPORT_C TInt NotifyRadioTextPlusChange( RArray<TInt>& aRtPlusClasses );

   737 

   738 	/**

   739      * Cancel NotifyRadioTextPlusChange request.

   740      *

   741      * @since S60 3.2

   742      */

   743 	IMPORT_C void CancelNotifyRadioTextPlusChange();

   744 

   745 	/**

   746      * Turn on/off automatic switching of frequency based on Alternate Frequency.

   747      * This will cause RDS device to search for alternate frequency when the signal strength

   748      * deteriorates. User should be ready to receive RadioEventRdsSearchBeginAF and

   749      * RadioEventRdsSearchEndAF. Automatic switching is off by default.

   750      *

   751      * @since S60 3.2

   752      * @param aAuto ETrue to turn automatic switching on, EFalse to turn it off.

   753      * @return A standard system/RadioServer error code.

   754      * @see MRadioObserver::RadioEventRdsSearchBeginAF

   755 	 * @see MRadioObserver::RadioEventRdsSearchEndAF

   756      */

   757 	IMPORT_C TInt SetAutomaticSwitching( TBool aAuto );

   758 

   759 	/**

   760      * Find out whether automatic switching is on or off.

   761      *

   762      * @since S60 3.2

   763      * @param aAuto On return, ETrue indicates that automatic switching is enabled.

   764      * @return A standard system/RadioServer error code.

   765      */

   766 	IMPORT_C TInt GetAutomaticSwitching( TBool& aAuto );

   767 

   768 	/**

   769      * Cancel ongoing search for an Alternate Frequency (AF) with stronger signal.

   770      *

   771      * Client can issue this request to interrupt the search indicated with

   772      * MRadioObserver::RadioEventRdsSearchBeginAF.

   773      *

   774      * @since S60 3.2

   775      */

   776 	IMPORT_C void CancelAFSearch();

   777 

   778 	/**

   779      * Turns on/off automatic switching of frequency based on Traffic Announcement.

   780      * This will cause RDS device to search for frequencies broadcasting traffic announcement.

   781      * Client will be notified of frequency change though the tuner event.

   782      * It's up to the client to return to the previous frequency when the traffic announcement

   783      * is finished.

   784      *

   785      * NOTE: This is only supported in dual tuner configuration since the secondary tuner

   786      * needs to perform continuous scanning for frequency broadcasting traffic announcement,

   787      * while the primary tuner is used for normal tuner activities.

   788      *

   789      * @since S60 3.2

   790      * @param aAuto ETrue indicates that automatic switching is on.

   791      * @return A standard system/RadioServer error code.

   792      */

   793 	IMPORT_C TInt SetAutomaticTrafficAnnouncement( TBool aAuto );

   794 

   795 	/**

   796      * Find out whether automatic traffic announcement is enabled.

   797      *

   798      * @since S60 3.2

   799      * @param aAuto On return, ETrue indicates that automatic traffic announcement is on.

   800      * @return A standard system/RadioServer error code.

   801      */

   802 	IMPORT_C TInt GetAutomaticTrafficAnnouncement( TBool& aAuto );

   803 

   804 	/**

   805      * Asynchronous request to find a radio station with the specified Programme Type(PTY),

   806      * starting from the currently tuned frequency and searching in the direction specified

   807      * (i.e. up or down). User must be ready to receive callback method StationSeekByPTYComplete

   808      * The station found is returned in the callback.

   809      *

   810      * @since S60 3.2

   811      * @param aPty The type of programme to search for.

   812      * @param aSeekUp The direction to search in. Searches upwards if set to ETrue.

   813      * @see MRadioObserver::StationSeekByPTYComplete

   814      */

   815 	IMPORT_C void StationSeekByPTY( TRsRdsProgrammeType aPty, TBool aSeekUp );

   816 

   817 	/**

   818      * Asynchronous request to find a radio station with Traffic Announcement(TA),

   819      * starting from the currently tuned frequency and searching in the direction specified

   820      * (i.e. up or down). User must be ready to receive callback method StationSeekByTAComplete

   821      * The station found is returned in the callback.

   822      *

   823      * @since S60 3.2

   824      * @param aSeekUp The direction to search in. Searches upwards if set to ETrue.

   825      * @see MRadioObserver::StationSeekByTAComplete

   826      */

   827 	IMPORT_C void StationSeekByTA( TBool aSeekUp );

   828 

   829 	/**

   830      * Asynchronous request to find a radio station with Traffic Programme(TP),

   831      * starting from the currently tuned frequency and searching in the direction specified

   832      * (i.e. up or down). User must be ready to receive callback method StationSeekByTPComplete

   833      * The station found is returned in the callback.

   834      *

   835      * @since S60 3.2

   836      * @param aSeekUp The direction to search in. Searches upwards if set to ETrue.

   837      * @see MRadioObserver::StationSeekByTPComplete

   838      */

   839 	IMPORT_C void StationSeekByTP( TBool aSeekUp );

   840 

   841 	/**

   842      * Cancels an ongoing retune operation, as initiated by a call to StationSeekByPTY,

   843      * StationSeekByTA, or StationSeekByTP.

   844      * The usual callback will not occur if this has been called.

   845      *

   846      * @since S60 3.2

   847      */

   848 	IMPORT_C void CancelRdsStationSeek();

   849 

   850 	/**

   851      * Asynchronous request to find all frequencies sending the given Programme Type (PTY).

   852      * User must be ready to receive callback method GetFreqByPTYComplete.

   853      *

   854      * NOTE: This is only supported in dual tuner configuration since the secondary tuner

   855      * needs to perform continuous scanning for frequencies broadcasting given Programme Type

   856      * while the primary tuner is used for normal tuner activities.

   857      * Client should first check the tuner capabilities. Will return KErrNotSupported in

   858      * callback method if this feature is not supported.

   859      *

   860      * @since S60 3.2

   861      * @param aPty The type of programme to search for

   862      * @see MRadioObserver::GetFreqByPTYComplete

   863      */

   864 	IMPORT_C void GetFreqByPTY( TRsRdsProgrammeType aPty );

   865 

   866 	/**

   867      * Cancels an ongoing request to find all frequencies sending a given Programme Type (PTY).

   868      * The usual callback will not occur if this has been called.

   869      *

   870      * @since S60 3.2

   871      */

   872 	IMPORT_C void CancelGetFreqByPTY();

   873 

   874 	/**

   875      * Asynchronous request to find all frequencies sending Traffic Announcement (TA). User must

   876      * be ready to receive callback method GetFreqByTAComplete.

   877      *

   878      * NOTE: This is only supported in dual tuner configuration since the secondary tuner

   879      * needs to perform continuous scanning for frequencies broadcasting given Traffic Announcement

   880      * while the primary tuner is used for normal tuner activities.

   881      * Client should first check the tuner capabilities. Will return KErrNotSupported in

   882      * callback method if this feature is not supported.

   883      *

   884      * @since S60 3.2

   885      * @see MRadioObserver::GetFreqByTAComplete

   886      */

   887 	IMPORT_C void GetFreqByTA();

   888 

   889 	/**

   890      * Cancels an ongoing request to find all frequencies sending Traffic Announcement.

   891      * The usual callback will not occur if this has been called.

   892      *

   893      * @since S60 3.2

   894      */

   895 	IMPORT_C void CancelGetFreqByTA();

   896 

   897 	/**

   898      * Asynchronous request to find all Programme Service names (PS) sending the given Programme

   899      * Type (PTY). User must be ready to receive callback method GetPSByPTYComplete.

   900      *

   901      * NOTE: This is only supported in dual tuner configuration since the secondary tuner

   902      * needs to perform continuous scanning for frequencies broadcasting given Programme Type

   903      * while the primary tuner is used for normal tuner activities.

   904      * Client should first check the tuner capabilities. Will return KErrNotSupported in

   905      * callback method if this feature is not supported.

   906      *

   907      * @since S60 3.2

   908      * @param aPty The type of programme to search for

   909      * @see MRadioObserver::GetPSByPTYComplete

   910      */

   911 	IMPORT_C void GetPSByPTY( TRsRdsProgrammeType aPty );

   912 

   913 	/**

   914      * Cancels an ongoing request to find all Programme Service names (PS) sending a given

   915      * Programme Type (PTY). The usual callback will not occur if this has been called.

   916      *

   917      * @since S60 3.2

   918      */

   919 	IMPORT_C void CancelGetPSByPTY();

   920 

   921 	/**

   922      * Asynchronous request to find all Programme Service names (PS) sending Traffic Announcement (TA).

   923      * User must be ready to receive callback method GetPSByTAComplete.

   924      *

   925      * NOTE: This is only supported in dual tuner configuration since the secondary tuner

   926      * needs to perform continuous scanning for frequencies broadcasting given Traffic Announcement

   927      * while the primary tuner is used for normal tuner activities.

   928      * Client should first check the tuner capabilities. Will return KErrNotSupported in

   929      * callback method if this feature is not supported.

   930      *

   931      * @since S60 3.2

   932      * @see MRadioObserver::GetPSByTAComplete

   933      */

   934 	IMPORT_C void GetPSByTA();

   935 

   936 	/**

   937      * Cancels an ongoing request to find all Programme Service names (PS) sending Traffic Announcement.

   938      * The usual callback will not occur if this has been called.

   939      *

   940      * @since S60 3.2

   941      */

   942 	IMPORT_C void CancelGetPSByTA();

   943 

   944 	/**

   945      * Get the current Programme Identification code.

   946      * RDS data is received over the air and may not be available immediately following

   947      * tune operation. If data is not available, this function will return KErrNotFound.

   948      * If a value is returned, this is the last known value, which may not be up to date.

   949      * To be notified of the most recent value, client should use NotifyRdsDataChange.

   950      *

   951      * @since S60 3.2

   952      * @param aPi On return contains Programme Identification code

   953      * @return A standard system/RadioServer error code.

   954      */

   955 	IMPORT_C TInt GetProgrammeIdentification( TInt& aPi );

   956 

   957 	/**

   958      * Get the current Programme Type.

   959      * RDS data is received over the air and may not be available immediately following

   960      * tune operation. If data is not available, this function will return KErrNotFound.

   961      * If a value is returned, this is the last known value, which may not be up to date.

   962      * To be notified of the most recent value, client should use NotifyRdsDataChange.

   963      *

   964      * @since S60 3.2

   965      * @param aPty On return contains Programme Type

   966      * @return A standard system/RadioServer error code.

   967      */

   968 	IMPORT_C TInt GetProgrammeType( TRsRdsProgrammeType& aPty );

   969 

   970 	/**

   971      * Get the current Programme Service name.

   972      * RDS data is received over the air and may not be available immediately following

   973      * tune operation. If data is not available, this function will return KErrNotFound.

   974      * If a value is returned, this is the last known value, which may not be up to date.

   975      * To be notified of the most recent value, client should use NotifyRdsDataChange.

   976      *

   977      * Programme Service name is fixed to 8 characters.

   978      *

   979      * @since S60 3.2

   980      * @param aPs On return contains Programme Service name

   981      * @return A standard system/RadioServer error code.

   982      */

   983 	IMPORT_C TInt GetProgrammeService( TRsRdsPSName& aPs );

   984 

   985 	/**

   986      * Get the current Radio Text.

   987      * RDS data is received over the air and may not be available immediately following

   988      * tune operation. If data is not available, this function will return KErrNotFound.

   989      * If a value is returned, this is the last known value, which may not be up to date.

   990      * To be notified of the most recent value, client should use NotifyRdsDataChange.

   991      *

   992      * The maximum possible length for radio text field is 64 characters.

   993      *

   994      * @since S60 3.2

   995      * @param aRt On return contains Radio Text

   996      * @return A standard system/RadioServer error code.

   997      */

   998 	IMPORT_C TInt GetRadioText( TRsRdsRadioText& aRt );

   999 

  1000     /**

  1001      * Get the current Radio Text+.

  1002      * RDS data is received over the air and may not be available immediately following

  1003      * tune operation. If data is not available, this function will return KErrNotFound.

  1004      * If a value is returned, this is the last known value, which may not be up to date.

  1005      * To be notified of the most recent value, client should use NotifyRdsDataChange.

  1006      *

  1007      * The maximum possible length for radio text+ field is 64 characters.

  1008      *

  1009      * @since S60 3.2

  1010      * @param aRtPlusClass Radio text plus class

  1011      * @param aRtPlusData On return contains Radio Text+ field

  1012      * @return A standard system/RadioServer error code.

  1013      */

  1014     IMPORT_C TInt GetRadioTextPlus( TRsRdsRTplusClass aRtPlusClass, TRsRdsRadioText& aRtPlusData );

  1015 

  1016 	/**

  1017      * Get the current Clock Time and date.

  1018      * RDS data is received over the air and may not be available immediately following

  1019      * tune operation. If data is not available, this function will return KErrNotFound.

  1020      * If a value is returned, this is the last known value, which may not be up to date.

  1021      * To be notified of the most recent value, client should use NotifyRdsDataChange.

  1022      *

  1023      * @since S60 3.2

  1024      * @param aCt On return contains current time and date

  1025      * @return A standard system/RadioServer error code.

  1026      */

  1027 	IMPORT_C TInt GetClockTime( TDateTime& aCt );

  1028 

  1029 	/**

  1030      * Get Traffic Announcement status at the current station.

  1031      *

  1032      * @since S60 3.2

  1033      * @param aTaStatus On return, will be ETrue if current station has ongoing traffic announcement

  1034      * @return A standard system/RadioServer error code.

  1035      */

  1036 	IMPORT_C TInt GetTrafficAnnouncementStatus( TBool& aTaStatus );

  1037 

  1038 	/**

  1039      * Get Traffic Programme status at the current station.

  1040      *

  1041      * @since S60 3.2

  1042      * @param aTpStatus On return, will be ETrue if current station supports traffic programme

  1043      * @return A standard system/RadioServer error code.

  1044      */

  1045 	IMPORT_C TInt GetTrafficProgrammeStatus( TBool& aTpStatus );

  1046 

  1047 // from base class MCustomCommand

  1048 

  1049     /**

  1050      * From MCustomCommand

  1051      * Sends a synchronous custom command to the radio server.

  1052      *

  1053      * @since S60 3.0

  1054      * @param aDestination The destination of the message, consisting of the uid of

  1055      * 		 the interface of this message

  1056      * @param aFunction The function number to indicate which function is to be called

  1057      *		 on the interface defined in the aDestination parameter

  1058      * @param aDataTo1 The first chunk of data to be copied to the controller

  1059      *		 framework. The exact contents of the data are dependent on the

  1060      *		 interface being called. Can be KNullDesC8.

  1061      * @param aDataTo2 The second chunk of data to be copied to the controller

  1062      *		 framework. The exact contents of the data are dependent on the

  1063      *		 interface being called. Can be KNullDesC8.

  1064      * @return A standard system error code.

  1065      */

  1066 	IMPORT_C  TInt CustomCommandSync( const TMMFMessageDestinationPckg& aDestination,

  1067 					TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2 );

  1068 

  1069 	/**

  1070      * From MCustomCommand

  1071      * Sends a synchronous custom command to the radio server.

  1072      *

  1073      * @since S60 3.0

  1074      * @param aDestination The destination of the message, consisting of the uid of

  1075      *		 the interface of this message

  1076      * @param aFunction The function number to indicate which function is to be called

  1077      *		 on the interface defined in the aDestination parameter

  1078      * @param aDataTo1 The first chunk of data to be copied to the controller

  1079      *		 framework. The exact contents of the data are dependent on the

  1080      *		 interface being called. Can be KNullDesC8.

  1081      * @param aDataTo2 The second chunk of data to be copied to the controller

  1082      *		 framework. The exact contents of the data are dependent on the

  1083      *		 interface being called. Can be KNullDesC8.

  1084      * @param aDataFrom The area of memory to which the controller framework

  1085      *		 will write any data to be passed back to the client. Can't be KNullDesC8.

  1086      * @return A standard system error code.

  1087      */

  1088 	IMPORT_C  TInt CustomCommandSync( const TMMFMessageDestinationPckg& aDestination,

  1089 					TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom );

  1090 

  1091 	/**

  1092      * From MCustomCommand

  1093      * Sends an asynchronous custom command to the radio server.

  1094      *

  1095      * @since S60 3.0

  1096      * @param aDestination The destination of the message, consisting of the uid of

  1097      *		 the interface of this message

  1098      * @param aFunction The function number to indicate which function is to be called

  1099      *		 on the interface defined in the aDestination parameter

  1100      * @param aDataTo1 The first chunk of data to be copied to the controller

  1101      *		 framework. The exact contents of the data are dependent on the

  1102      *		 interface being called. Can be KNullDesC8.

  1103      * @param aDataTo2 The second chunk of data to be copied to the controller

  1104      *		 framework. The exact contents of the data are dependent on the

  1105      *		 interface being called. Can be KNullDesC8.

  1106      * @param aStatus The TRequestStatus of an active object. This will contain the

  1107      *		 result of the request on completion.  The exact range of result values is

  1108      *		 dependent on the interface.

  1109      */

  1110 	IMPORT_C  void CustomCommandAsync( const TMMFMessageDestinationPckg& aDestination,

  1111 					TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus );

  1112 

  1113 	/**

  1114      * From MCustomCommand

  1115      * Sends an asynchronous custom command to the radio server.

  1116      *

  1117      * @since S60 3.0

  1118      * @param aDestination The destination of the message, consisting of the uid of

  1119      *		 the interface of this message

  1120      * @param aFunction The function number to indicate which function is to be called

  1121      *		 on the interface defined in the aDestination parameter

  1122      * @param aDataTo1 The first chunk of data to be copied to the controller

  1123      *		 framework. The exact contents of the data are dependent on the

  1124      *		 interface being called. Can be KNullDesC8.

  1125      * @param aDataTo2 The second chunk of data to be copied to the controller

  1126      *		 framework. The exact contents of the data are dependent on the

  1127      *		 interface being called. Can be KNullDesC8.

  1128      * @param aDataFrom The area of memory to which the controller framework

  1129      *		 will write any data to be passed back to the client. Can't be KNullDesC8.

  1130      * @param aStatus The TRequestStatus of an active object. This will contain the

  1131      *		 result of the request on completion.  The exact range of result values is

  1132      *		 dependent on the interface.

  1133      */

  1134 	IMPORT_C  void CustomCommandAsync( const TMMFMessageDestinationPckg& aDestination, TInt aFunction,

  1135 					const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus );