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 

    33 // FORWARD DECLARATIONS

    34 class CRadioRequest;

    35 class CRadioEventHandler;

    36 

    37 // CLASS DECLARATION

    38 

    39 /**

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

    41 *  events from the radio server.

    42 *

    43 *  @lib RadioSession.lib

    44 *  @since S60 3.0

    45 */

    46 class MRadioObserver

    47     {

    48 public: // New functions

    49 

    50 //********** Tuner related

    51 

    52 	/**

    53      * Completion message for RequestTunerControl request.

    54      *

    55      * @since S60 3.2

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

    57      */

    58 	virtual void RequestTunerControlComplete( TRadioServerError aError ) = 0;

    59 

    60 	/**

    61      * Completion message for SetFrequencyRange request.

    62      *

    63      * @since S60 3.2

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

    65      */

    66 	virtual void SetFrequencyRangeComplete( TRadioServerError aError ) = 0;

    67 

    68 	/**

    69      * Completion message for SetFrequency request.

    70      *

    71      * @since S60 3.0

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

    73      */

    74 	virtual void SetFrequencyComplete( TRadioServerError aError ) = 0;

    75 

    76 	/**

    77      * Completion message for StationSeek request.

    78      *

    79      * @since S60 3.0

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

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

    82      */

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

    84 

    85 	/**

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

    87      * is turned off when FM transmitter is active.

    88      *

    89      * @since S60 3.2

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

    91      */

    92 	virtual void RadioEventTransmitterStatusChange( TBool aActive ) = 0;

    93 

    94 	/**

    95      * Event notification indicating antenna status change.

    96      *

    97      * @since S60 3.0

    98      * @param aAttached ETrue if antenna is attached.

    99      */

   100 	virtual void RadioEventAntennaStatusChange( TBool aAttached ) = 0;

   101 

   102 	/**

   103      * Event notification indicating offline mode change.

   104      *

   105      * @since S60 3.0

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

   107      */

   108 	virtual void RadioEventOfflineModeChange( TBool aOfflineMode ) = 0;

   109 

   110 	/**

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

   112      * other applications.

   113      *

   114      * @since S60 3.2

   115      * @param aNewRange New frequency range.

   116      */

   117 	virtual void RadioEventFrequencyRangeChanged( TRsFrequencyRange aNewRange ) = 0;

   118 

   119 	/**

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

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

   122      *

   123      * @since S60 3.2

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

   125      */

   126 	virtual void RadioEventFrequencyChange( TInt aFrequency ) = 0;

   127 

   128 	/**

   129      * Event notification indicating forced mono status change.

   130      *

   131      * @since S60 3.2

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

   133      */

   134 	virtual void RadioEventForcedMonoChanged( TBool aForcedMono ) = 0;

   135 

   136 	/**

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

   138      *

   139      * @since S60 3.2

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

   141      */

   142 	virtual void RadioEventSquelchChanged( TBool aSquelch ) = 0;

   143 

   144 //********** Player related

   145 

   146 	/**

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

   148      * other applications.

   149      *

   150      * @since S60 3.0

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

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

   153      */

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

   155 

   156 	/**

   157      * Event notification indicating volume change.

   158      *

   159      * @since S60 3.2

   160      * @param aVolume New volume.

   161      */

   162 	virtual void RadioEventVolumeChange( TInt aVolume ) = 0;

   163 

   164 	/**

   165      * Event notification indicating mute setting change.

   166      *

   167      * @since S60 3.2

   168      * @param aMute ETrue indicates audio is muted.

   169      */

   170 	virtual void RadioEventMuteChange( TBool aMute ) = 0;

   171 

   172 	/**

   173      * Event notification indicating balance setting change.

   174      *

   175      * @since S60 3.2

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

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

   178      */

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

   180 

   181 //********** RDS related

   182 

   183 	/**

   184      * Completion message for StationSeekByPTY request.

   185      *

   186      * @since S60 3.2

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

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

   189      */

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

   191 

   192 	/**

   193      * Completion message for StationSeekByTA request.

   194      *

   195      * @since S60 3.2

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

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

   198      */

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

   200 

   201 	/**

   202      * Completion message for StationSeekByTP request.

   203      *

   204      * @since S60 3.2

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

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

   207      */

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

   209 

   210 	/**

   211      * Completion message for GetFreqByPTY request.

   212      *

   213      * @since S60 3.2

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

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

   216      */

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

   218 

   219 	/**

   220      * Completion message for GetFreqByTA request.

   221      *

   222      * @since S60 3.2

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

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

   225      */

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

   227 

   228 	/**

   229      * Completion message for StatGetPSByPTY request.

   230      *

   231      * @since S60 3.2

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

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

   234      */

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

   236 

   237 	/**

   238      * Completion message for GetPSByTA request.

   239      *

   240      * @since S60 3.2

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

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

   243      */

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

   245 

   246 	/**

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

   248      *

   249      * @since S60 3.2

   250      * @param aPi Programme identification

   251      */

   252 	virtual void RadioEventRdsDataPI( TInt aPi ) = 0;

   253 

   254 	/**

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

   256      *

   257      * @since S60 3.2

   258      * @param aPty Programme type

   259      */

   260 	virtual void RadioEventRdsDataPTY( TRsRdsProgrammeType aPty ) = 0;

   261 

   262 	/**

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

   264      *

   265      * @since S60 3.2

   266      * @param aPs Programme service

   267      */

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

   269 

   270 	/**

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

   272      *

   273      * @since S60 3.2

   274      * @param aRt Radio text

   275      */

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

   277 

   278 	/**

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

   280      *

   281      * @since S60 3.2

   282      * @param aCt Clock time

   283      */

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

   285 

   286 	/**

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

   288      *

   289      * @since S60 3.2

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

   291      */

   292 	virtual void RadioEventRdsDataTA( TBool aTaOn ) = 0;

   293 

   294 	/**

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

   296      *

   297      * @since S60 3.2

   298 	 * @param aRtPlusClass Radio text plus class

   299 	 * @param aRtPlusData Radio text plus data

   300 	 */

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

   302 

   303 	/**

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

   305      *

   306      * @since S60 3.2

   307      */

   308 	virtual void RadioEventRdsSearchBeginAF() = 0;

   309 

   310 	/**

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

   312      *

   313      * @since S60 3.2

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

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

   316      */

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

   318 

   319 	/**

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

   321      * broadcasting Traffic Announcement(TA).

   322      *

   323      * @since S60 3.2

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

   325      */

   326 	virtual void RadioEventRdsStationChangeTA( TInt aFrequency ) = 0;

   327 

   328 	/**

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

   330      *

   331      * @since S60 3.2

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

   333      */

   334 	virtual void RadioEventRdsAutomaticSwitchingChange( TBool aAuto ) = 0;

   335 

   336 	/**

   337      * Event notification indicating automatic traffic announcement setting change.

   338      *

   339      * @since S60 3.2

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

   341      */

   342 	virtual void RadioEventRdsAutomaticTrafficAnnouncement( TBool aAuto ) = 0;

   343 

   344 	/**

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

   346      *

   347      * @since S60 3.2

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

   349      */

   350 	virtual void RadioEventRdsSignalChange( TBool aSignal ) = 0;

   351     };

   352 

   353 /**

   354 *  Main interface to the Radio Server.

   355 *  Implements the client-side session.

   356 *

   357 *  @lib RadioSession.lib

   358 *  @since S60 3.0

   359 */

   360 class RRadioSession : public RSessionBase,

   361 					  public MCustomCommand

   362     {

   363 public:  // Constructors and destructor

   364 

   365 	/**

   366      * C++ default constructor.

   367      */

   368 	IMPORT_C RRadioSession();

   369 

   370 public: // New functions

   371 

   372 	/**

   373      * Connects a client to the radio server.

   374      * @since S60 3.0

   375      *

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

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

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

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

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

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

   382      * @return A standard system error code.

   383      */

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

   385 

   386 	/**

   387      * Gets the client side version number.

   388      *

   389      * @since S60 3.0

   390      * @return The client side version number.

   391      */

   392 	IMPORT_C TVersion Version() const;

   393 

   394 	/**

   395      * Closes connection to the radio server.

   396      *

   397      * @since S60 3.0

   398      */

   399 	IMPORT_C void Close();

   400 

   401 //********** TunerUtility control begins

   402 

   403 	/**

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

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

   406      * other request can be made.

   407      *

   408      * @since S60 3.2

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

   410      * @return A standard system error code.

   411      * @see MRadioObserver::RequestTunerControlComplete

   412      */

   413 	IMPORT_C void RequestTunerControl( TRsTuner aTuner );

   414 

   415 	/**

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

   417      *

   418      * @since S60 3.2

   419      * @param aCaps The capabilities object to fill

   420      * @return A standard system error code.

   421      */

   422 	IMPORT_C TInt GetTunerCapabilities( TRsTunerCapabilities& aCaps ) const;

   423 

   424 	/**

   425      * EnableTunerInOfflineMode on the device.

   426      *

   427      * @since S60 3.2

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

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

   430      */

   431 	IMPORT_C TInt EnableTunerInOfflineMode( TBool aEnable );

   432 

   433 	/**

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

   435      * it will be defaulted to ERsTunerFM.

   436      *

   437      * @since S60 3.2

   438      * @param aRange Frequency range

   439      * @see MRadioObserver::SetFrequencyRangeComplete

   440      */

   441 	IMPORT_C void SetFrequencyRange( TRsFrequencyRange aRange );

   442 

   443 	/**

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

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

   446      *

   447      * @since S60 3.2

   448      * @return A standard system error code.

   449      */

   450 	IMPORT_C void CancelSetFrequencyRange();

   451 

   452 	/**

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

   454      * for the returned range.

   455      *

   456      * @since S60 3.2

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

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

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

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

   461      */

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

   463 

   464 	/**

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

   466      *

   467      * @since S60 3.2

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

   469      * @see MRadioObserver::SetFrequecyComplete

   470      */

   471 	IMPORT_C void SetFrequency( TInt aFrequency );

   472 

   473 	/**

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

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

   476      *

   477      * @since S60 3.0

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

   479      */

   480 	IMPORT_C void CancelSetFrequency();

   481 

   482 	/**

   483      * Get the current frequency.

   484      *

   485      * @since S60 3.2

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

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

   488      */

   489 	IMPORT_C TInt GetFrequency( TInt& aFrequency ) const;

   490 

   491 	/**

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

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

   494      *

   495      * @since S60 3.0

   496      * @param aSeekUp Search direction

   497      * @see MRadioObserver::StationSeekComplete

   498      */

   499 	IMPORT_C void StationSeek( TBool aUpwards );

   500 

   501 	/**

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

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

   504      *

   505      * @since S60 3.0

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

   507      */

   508 	IMPORT_C void CancelStationSeek();

   509 

   510 	/**

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

   512      *

   513      * @since S60 3.2

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

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

   516      */

   517 	IMPORT_C TInt GetSignalStrength( TInt& aSignalStrength ) const;

   518 

   519 	/**

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

   521      *

   522      * @since S60 3.2

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

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

   525      */

   526 	IMPORT_C TInt GetMaxSignalStrength( TInt& aMaxSignalStrength ) const;

   527 

   528 	/**

   529      * Get the stereo mode of the radio.

   530      *

   531      * @since S60 3.2

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

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

   534      */

   535 	IMPORT_C TInt GetStereoMode( TBool& aStereo ) const;

   536 

   537 	/**

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

   539      *

   540      * @since S60 3.2

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

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

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

   544      */

   545 	IMPORT_C TInt ForceMonoReception( TBool aForcedMono );

   546 

   547 	/**

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

   549      * @since S60 3.2

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

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

   552      */

   553 	IMPORT_C TInt GetForceMonoReception( TBool& aForcedMono ) const;

   554 

   555 	/**

   556      * Enable or disable quelch.

   557      *

   558      * @since S60 3.2

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

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

   561      */

   562 	IMPORT_C TInt SetSquelch( TBool aEnabled );

   563 

   564 	/**

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

   566      *

   567      * @since S60 3.2

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

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

   570      */

   571 	IMPORT_C TInt GetSquelch( TBool& aSquelch ) const;

   572 

   573 //********** PlayerUtility control begins

   574 

   575 	/**

   576      * Retrieve the current state of the player.

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

   578      * as volume, etc.

   579      *

   580      * @since S60 3.2

   581      * @return Radio player state.

   582      */

   583 	IMPORT_C TInt PlayerState( TRsPlayerState& aState ) const;

   584 

   585 	/**

   586      * Starts radio playback.

   587      *

   588      * @since S60 3.0

   589      */

   590 	IMPORT_C void Play();

   591 

   592 	/**

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

   594      *

   595      * @since S60 3.0

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

   597      */

   598 	IMPORT_C void Stop( TBool aIfOnlyPrimaryClient = EFalse );

   599 

   600 	/**

   601      * Retrieves the maximum volume supported.

   602      *

   603      * @since S60 3.0

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

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

   606      */

   607 	IMPORT_C TInt GetMaxVolume( TInt& aMaxVolume ) const;

   608 

   609 	/**

   610      * Sets the volume to the specified level.

   611      *

   612      * @since S60 3.0

   613      * @param aVolume The volume level to set

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

   615      */

   616 	IMPORT_C TInt SetVolume( TInt aVolume );

   617 

   618 	/**

   619      * Get the current volume.

   620      *

   621      * @since S60 3.2

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

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

   624      */

   625 	IMPORT_C TInt GetVolume( TInt& aVolume ) const;

   626 

   627 	/**

   628      * Set a volume ramp.

   629      *

   630      * @since S60 3.2

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

   632      *		 zero to the current volume setting.

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

   634      */

   635 	IMPORT_C TInt SetVolumeRamp( const TTimeIntervalMicroSeconds& aRampInterval );

   636 

   637 	/**

   638      * Mutes or unmutes playback.

   639      *

   640      * @since S60 3.0

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

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

   643      */

   644 	IMPORT_C TInt Mute( TBool aMute );

   645 

   646 	/**

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

   648      *

   649      * @since S60 3.2

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

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

   652      */

   653 	IMPORT_C TInt GetMuteStatus( TBool& aMute ) const;

   654 

   655 	/**

   656      * Set the speaker balance for playing.

   657      *

   658      * @since S60 3.2

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

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

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

   662      */

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

   664 

   665 	/**

   666      * Get the current speaker balance setting.

   667      *

   668      * @since S60 3.2

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

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

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

   672      */

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

   674 

   675 //********** RDSUtility control begins

   676 

   677 	/**

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

   679      *

   680      * @since S60 3.2

   681      * @param aCaps The capabilities object to fill

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

   683      */

   684 	IMPORT_C TInt GetRdsCapabilities( TRsRdsCapabilities& aCaps ) const;

   685 

   686 	/**

   687      * Get the status of the RDS reception.

   688      *

   689      * @since S60 3.2

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

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

   692      */

   693 	IMPORT_C TInt GetRdsSignalStatus( TBool& aRdsSignal ) const;

   694 

   695 	/**

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

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

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

   699      *

   700      * @since S60 3.2

   701      * @param aRdsData Bitfield indicating notification request.

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

   703      * @see MRadioObserver::RadioEventRdsDataPI

   704      * @see MRadioObserver::RadioEventRdsDataPTY

   705      * @see MRadioObserver::RadioEventRdsDataPS

   706      * @see MRadioObserver::RadioEventRdsDataRT

   707      * @see MRadioObserver::RadioEventRdsDataCT

   708      * @see MRadioObserver::RadioEventRdsDataTA

   709      */

   710 	IMPORT_C TInt NotifyRdsDataChange( TRsRdsData aRdsData );

   711 

   712 	/**

   713      * Cancel NotifyRdsDataChange request.

   714      *

   715      * @since S60 3.2

   716      */

   717 	IMPORT_C void CancelNotifyRdsDataChange();

   718 

   719     /**

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

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

   722      * Returns KErrNotSupported if RT+ is not supported.

   723      *

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

   725      * subscribe for ERsRdsRadioText using NotifyRdsDataChange instead.

   726      *

   727      * @since S60 3.2

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

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

   730      * @see MRadioObserver::RadioEventRdsDataRTplus

   731      */

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

   733 

   734 	/**

   735      * Cancel NotifyRadioTextPlusChange request.

   736      *

   737      * @since S60 3.2

   738      */

   739 	IMPORT_C void CancelNotifyRadioTextPlusChange();

   740 

   741 	/**

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

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

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

   745      * RadioEventRdsSearchEndAF. Automatic switching is off by default.

   746      *

   747      * @since S60 3.2

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

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

   750      * @see MRadioObserver::RadioEventRdsSearchBeginAF

   751 	 * @see MRadioObserver::RadioEventRdsSearchEndAF

   752      */

   753 	IMPORT_C TInt SetAutomaticSwitching( TBool aAuto );

   754 

   755 	/**

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

   757      *

   758      * @since S60 3.2

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

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

   761      */

   762 	IMPORT_C TInt GetAutomaticSwitching( TBool& aAuto );

   763 

   764 	/**

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

   766      *

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

   768      * MRadioObserver::RadioEventRdsSearchBeginAF.

   769      *

   770      * @since S60 3.2

   771      */

   772 	IMPORT_C void CancelAFSearch();

   773 

   774 	/**

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

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

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

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

   779      * is finished.

   780      *

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

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

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

   784      *

   785      * @since S60 3.2

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

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

   788      */

   789 	IMPORT_C TInt SetAutomaticTrafficAnnouncement( TBool aAuto );

   790 

   791 	/**

   792      * Find out whether automatic traffic announcement is enabled.

   793      *

   794      * @since S60 3.2

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

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

   797      */

   798 	IMPORT_C TInt GetAutomaticTrafficAnnouncement( TBool& aAuto );

   799 

   800 	/**

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

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

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

   804      * The station found is returned in the callback.

   805      *

   806      * @since S60 3.2

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

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

   809      * @see MRadioObserver::StationSeekByPTYComplete

   810      */

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

   812 

   813 	/**

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

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

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

   817      * The station found is returned in the callback.

   818      *

   819      * @since S60 3.2

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

   821      * @see MRadioObserver::StationSeekByTAComplete

   822      */

   823 	IMPORT_C void StationSeekByTA( TBool aSeekUp );

   824 

   825 	/**

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

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

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

   829      * The station found is returned in the callback.

   830      *

   831      * @since S60 3.2

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

   833      * @see MRadioObserver::StationSeekByTPComplete

   834      */

   835 	IMPORT_C void StationSeekByTP( TBool aSeekUp );

   836 

   837 	/**

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

   839      * StationSeekByTA, or StationSeekByTP.

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

   841      *

   842      * @since S60 3.2

   843      */

   844 	IMPORT_C void CancelRdsStationSeek();

   845 

   846 	/**

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

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

   849      *

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

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

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

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

   854      * callback method if this feature is not supported.

   855      *

   856      * @since S60 3.2

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

   858      * @see MRadioObserver::GetFreqByPTYComplete

   859      */

   860 	IMPORT_C void GetFreqByPTY( TRsRdsProgrammeType aPty );

   861 

   862 	/**

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

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

   865      *

   866      * @since S60 3.2

   867      */

   868 	IMPORT_C void CancelGetFreqByPTY();

   869 

   870 	/**

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

   872      * be ready to receive callback method GetFreqByTAComplete.

   873      *

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

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

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

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

   878      * callback method if this feature is not supported.

   879      *

   880      * @since S60 3.2

   881      * @see MRadioObserver::GetFreqByTAComplete

   882      */

   883 	IMPORT_C void GetFreqByTA();

   884 

   885 	/**

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

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

   888      *

   889      * @since S60 3.2

   890      */

   891 	IMPORT_C void CancelGetFreqByTA();

   892 

   893 	/**

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

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

   896      *

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

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

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

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

   901      * callback method if this feature is not supported.

   902      *

   903      * @since S60 3.2

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

   905      * @see MRadioObserver::GetPSByPTYComplete

   906      */

   907 	IMPORT_C void GetPSByPTY( TRsRdsProgrammeType aPty );

   908 

   909 	/**

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

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

   912      *

   913      * @since S60 3.2

   914      */

   915 	IMPORT_C void CancelGetPSByPTY();

   916 

   917 	/**

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

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

   920      *

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

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

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

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

   925      * callback method if this feature is not supported.

   926      *

   927      * @since S60 3.2

   928      * @see MRadioObserver::GetPSByTAComplete

   929      */

   930 	IMPORT_C void GetPSByTA();

   931 

   932 	/**

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

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

   935      *

   936      * @since S60 3.2

   937      */

   938 	IMPORT_C void CancelGetPSByTA();

   939 

   940 	/**

   941      * Get the current Programme Identification code.

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

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

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

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

   946      *

   947      * @since S60 3.2

   948      * @param aPi On return contains Programme Identification code

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

   950      */

   951 	IMPORT_C TInt GetProgrammeIdentification( TInt& aPi );

   952 

   953 	/**

   954      * Get the current Programme Type.

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

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

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

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

   959      *

   960      * @since S60 3.2

   961      * @param aPty On return contains Programme Type

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

   963      */

   964 	IMPORT_C TInt GetProgrammeType( TRsRdsProgrammeType& aPty );

   965 

   966 	/**

   967      * Get the current Programme Service name.

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

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

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

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

   972      *

   973      * Programme Service name is fixed to 8 characters.

   974      *

   975      * @since S60 3.2

   976      * @param aPs On return contains Programme Service name

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

   978      */

   979 	IMPORT_C TInt GetProgrammeService( TRsRdsPSName& aPs );

   980 

   981 	/**

   982      * Get the current Radio Text.

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

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

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

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

   987      *

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

   989      *

   990      * @since S60 3.2

   991      * @param aRt On return contains Radio Text

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

   993      */

   994 	IMPORT_C TInt GetRadioText( TRsRdsRadioText& aRt );

   995 

   996     /**

   997      * Get the current Radio Text+.

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

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

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

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

  1002      *

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

  1004      *

  1005      * @since S60 3.2

  1006      * @param aRtPlusClass Radio text plus class

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

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

  1009      */

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

  1011 

  1012 	/**

  1013      * Get the current Clock Time and date.

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

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

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

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

  1018      *

  1019      * @since S60 3.2

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

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

  1022      */

  1023 	IMPORT_C TInt GetClockTime( TDateTime& aCt );

  1024 

  1025 	/**

  1026      * Get Traffic Announcement status at the current station.

  1027      *

  1028      * @since S60 3.2

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

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

  1031      */

  1032 	IMPORT_C TInt GetTrafficAnnouncementStatus( TBool& aTaStatus );

  1033 

  1034 	/**

  1035      * Get Traffic Programme status at the current station.

  1036      *

  1037      * @since S60 3.2

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

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

  1040      */

  1041 	IMPORT_C TInt GetTrafficProgrammeStatus( TBool& aTpStatus );

  1042 

  1043 // from base class MCustomCommand

  1044 

  1045     /**

  1046      * From MCustomCommand

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

  1048      *

  1049      * @since S60 3.0

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

  1051      * 		 the interface of this message

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

  1053      *		 on the interface defined in the aDestination parameter

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

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

  1056      *		 interface being called. Can be KNullDesC8.

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

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

  1059      *		 interface being called. Can be KNullDesC8.

  1060      * @return A standard system error code.

  1061      */

  1062 	IMPORT_C  TInt CustomCommandSync( const TMMFMessageDestinationPckg& aDestination,

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

  1064 

  1065 	/**

  1066      * From MCustomCommand

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

  1068      *

  1069      * @since S60 3.0

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

  1071      *		 the interface of this message

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

  1073      *		 on the interface defined in the aDestination parameter

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

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

  1076      *		 interface being called. Can be KNullDesC8.

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

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

  1079      *		 interface being called. Can be KNullDesC8.

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

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

  1082      * @return A standard system error code.

  1083      */

  1084 	IMPORT_C  TInt CustomCommandSync( const TMMFMessageDestinationPckg& aDestination,

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

  1086 

  1087 	/**

  1088      * From MCustomCommand

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

  1090      *

  1091      * @since S60 3.0

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

  1093      *		 the interface of this message

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

  1095      *		 on the interface defined in the aDestination parameter

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

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

  1098      *		 interface being called. Can be KNullDesC8.

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

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

  1101      *		 interface being called. Can be KNullDesC8.

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

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

  1104      *		 dependent on the interface.

  1105      */

  1106 	IMPORT_C  void CustomCommandAsync( const TMMFMessageDestinationPckg& aDestination,

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

  1108 

  1109 	/**

  1110      * From MCustomCommand

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

  1112      *

  1113      * @since S60 3.0

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

  1115      *		 the interface of this message

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

  1117      *		 on the interface defined in the aDestination parameter

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

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

  1120      *		 interface being called. Can be KNullDesC8.

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

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

  1123      *		 interface being called. Can be KNullDesC8.

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

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

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

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

  1128      *		 dependent on the interface.

  1129      */

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

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

  1132 

  1133 //********** Internal functions begin

  1134