1 /*

     2 * Copyright (c) 2006 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 provides an interface for controlling the FM tuner

    15 *                controls such as tuning or seeking frequencies. In addition an

    16 *                observer class is provided for receiving completion notification

    17 *                for asynchronous requests made to FM tuner control and for receiving

    18 *                events notifying changes in the tuner such as frequency change

    19 *                (caused by other clients or RDS, if supported), loss of tuner

    20 *                control,etc.

    21 *

    22 *

    23 */

    24 

    25 

    26 

    27 #ifndef C_RADIOFMTUNERUTILITY_H

    28 #define C_RADIOFMTUNERUTILITY_H

    29 

    30 #include <RadioUtility.h>

    31 

    32 class RRadioSession;

    33 

    34 /**

    35  *  FM tuner error definitions.

    36  *  In addition to the standard system error code, the following error codes may

    37  *  be returned.

    38  */

    39 typedef TInt TFmRadioTunerError;

    40 const TFmRadioTunerError KFmRadioErrHardwareFaulty              = -12050;

    41 const TFmRadioTunerError KFmRadioErrTuning                      = -12051;

    42 const TFmRadioTunerError KFmRadioErrFrequencyOutOfBandRange     = -12052;

    43 const TFmRadioTunerError KFmRadioErrFrequencyNotValid           = -12053;

    44 const TFmRadioTunerError KFmRadioErrNotPermittedInCurrentState 	= -12054;

    45 const TFmRadioTunerError KFmRadioErrDuplicateRequest            = -12055;

    46 const TFmRadioTunerError KFmRadioErrAntennaNotConnected	        = -12056;

    47 const TFmRadioTunerError KFmRadioErrFmTransmitterActive	        = -12057;

    48 const TFmRadioTunerError KFmRadioErrOfflineMode                 = -12058;

    49 

    50 

    51 /**  FM radio frequency range */

    52 enum TFmRadioFrequencyRange

    53     {

    54     EFmRangeEuroAmerica		= 0x01,		// European and American FM frequency range

    55     EFmRangeJapan			= 0x02		// Japanese FM frequency range

    56     };

    57 

    58 

    59 /**

    60  *  The FM Tuner Capabilities class defines the capabilities of the FM tuner on the

    61  *  device, as retrieved using the function GetCapabilities.

    62  *

    63  *  @since S60 3.2

    64  */

    65 class TFmTunerCapabilities

    66     {

    67 public:

    68     //  Tuner Features bit flags - may be extended in future

    69     enum TFmTunerFeatures

    70         {

    71         // This bit is set if the tuner can be used even when the device is in

    72 		// offline mode. Some tuner may not allow this due to hw conflict.

    73         ETunerAvailableInOfflineMode	  = 0x01,

    74         // This bit is set if the tuner has RDS support.

    75         ETunerRdsSupport                  = 0x02,

    76         // This bit is set when the device supports dual tuner, which allows

    77 		// more extensive RDS feature support.

    78         ETunerDualTunerSupport            = 0x04

    79         };

    80 

    81 public:

    82     // Bitfield (as defined by TFmRadioFrequencyRange) with the bits of the supported frequency range

    83     TUint32 iTunerBands;

    84     // Bitfield (as defined by TFmTunerFunctions) with the bits of the supported functions set

    85     TUint32 iTunerFunctions;

    86     // Reserved for future

    87     TUint32 iAdditionalFunctions1;

    88     // Reserved for future

    89     TUint32 iAdditionalFunctions2;

    90     };

    91 

    92 

    93 /**

    94  *  This class provides the interface class to be implemented by object receiving request

    95  *  complete notification from FM tuner control. These functions are called once the asynchronous

    96  *  request completes successfully or with an error.

    97  *

    98  *  In addition, this class provides the interface for receiving events from FM tuner control.

    99  *

   100  *  @since S60 3.2

   101  */

   102 class MRadioFmTunerObserver

   103     {

   104 public:

   105 

   106     /**

   107      * Request for tuner control complete event. This event is asynchronous and is received after

   108      * a call to CRadioFmTunerUtility::RequestTunerControl.

   109      *

   110      * If this function returns KErrNone, control of the tuner has been granted.

   111      *

   112      * If this function returns KFMRadioErrAntennaNotConnected, KFMRadioErrFmTransmitterActive,

   113      * or KFMRadioErrOfflineMode, client will receive the following events respectively:

   114      * MrfteoAntennaStatusChanged, MrfteoFmTransmitterStatusChanged, MrfteoOfflineModeStatusChanged.

   115      * At this time, client must re-issue RequestTunerControl. Note that functions that require

   116      * control of the tuner (such as Tune) will return one of the above error codes.

   117      *

   118      * In case of multiple clients accessing the tuner, or when RequestTunerControl is re-issued,

   119      * this function returns KErrAlreadyExists.

   120      *

   121      * @since S60 3.2

   122      * @param aError A standard system error code or FM tuner error (TFmRadioTunerError).

   123      */

   124     virtual void MrftoRequestTunerControlComplete( TInt aError ) = 0;

   125 

   126     /**

   127      * Set frequency range complete event. This event is asynchronous and is received after

   128      * a call to CRadioFmTunerUtility::SetFrequencyRange.

   129      *

   130      * @since S60 3.2

   131      * @param aError A standard system error code or FM tuner error (TFmRadioTunerError).

   132      */

   133     virtual void MrftoSetFrequencyRangeComplete( TInt aError ) = 0;

   134 

   135     /**

   136      * Set frequency complete event. This event is asynchronous and is received after a call to

   137 	 * CRadioFmTunerUtility::SetFrequency.

   138      *

   139      * @since S60 3.2

   140      * @param aError A standard system error code or FM tuner error (TFmRadioTunerError).

   141      */

   142     virtual void MrftoSetFrequencyComplete( TInt aError ) = 0;

   143 

   144     /**

   145      * Station seek complete event. This event is asynchronous and is received after a call to

   146 	 * CRadioFmTunerUtility::StationSeek.

   147      *

   148      * @since S60 3.2

   149      * @param aError A standard system error code or FM tuner error (TFmRadioTunerError).

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

   151      */

   152     virtual void MrftoStationSeekComplete( TInt aError, TInt aFrequency ) = 0;

   153 

   154     /**

   155      * Called when FM Transmitter status changes (if one is present in the device). Tuner receiver

   156      * is forced to be turned off due to hardware conflicts when FM transmitter is activated.

   157      *

   158      * @since S60 3.2

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

   160      */

   161     virtual void MrftoFmTransmitterStatusChange( TBool aActive ) = 0;

   162 

   163     /**

   164      * Called when antenna status changes.

   165      *

   166      * @since S60 3.2

   167      * @param aAttached ETrue if antenna is attached; EFalse otherwise.

   168      */

   169     virtual void MrftoAntennaStatusChange( TBool aAttached ) = 0;

   170 

   171     /**

   172      * Called when offline mode status changes.

   173      * @since S60 3.2

   174      *

   175      ** @param aAttached ETrue if offline mode is enabled; EFalse otherwise.

   176      */

   177     virtual void MrftoOfflineModeStatusChange( TBool aOfflineMode ) = 0;

   178 

   179     /**

   180      * Called when the frequency range changes. This may be caused by other applications.

   181      *

   182      * @since S60 3.2

   183      * @param aNewRange New frequency range.

   184      */

   185     virtual void MrftoFrequencyRangeChange( TFmRadioFrequencyRange aNewRange ) = 0;

   186 

   187     /**

   188      * Called when the tuned frequency changes. This may be caused by other

   189      * applications or RDS if AF/TA is enabled.

   190      *

   191      * @since S60 3.2

   192      * @param aNewFrequency The new tuned frequency(Hz).

   193      */

   194     virtual void MrftoFrequencyChange( TInt aNewFrequency ) = 0;

   195 

   196     /**

   197      * Called when the forced mono status change. This may be caused by other applications.

   198      *

   199      * @since S60 3.2

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

   201      */

   202     virtual void MrftoForcedMonoChange( TBool aForcedMono ) = 0;

   203 

   204     /**

   205      * Called when the squelch (muting the frequencies without broadcast) status change.

   206      * This may be caused by other applications.

   207      *

   208      * @since S60 3.2

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

   210      */

   211     virtual void MrftoSquelchChange( TBool aSquelch ) = 0;

   212 	};

   213 

   214 /**

   215  *  This class provides an interface to allow clients to control the FM tuner hardware

   216  *  present on a device.

   217  *

   218  *  @lib RadioUtility.lib

   219  *  @since S60 3.2

   220  */

   221 class CRadioFmTunerUtility : public CBase

   222     {

   223     friend class CRadioUtility::CBody;

   224 

   225 public:

   226 

   227     /**

   228      * Asynchronous request to get control of the FM tuner. This method call must be made before

   229      * any other method calls in this API.

   230      * User must be ready to receive callback method MrftoRequestTunerControlComplete. Control

   231      * to the tuner must be granted before any functions that require control of the tuner

   232      * (such as SetFrequency) can be made.

   233      * The only API call that doesn't require tuner control to be granted is EnableTunerInOfflineMode().

   234      *

   235      * @since S60 3.2

   236      * @see MRadioFmTunerObserver::MrftoRequestTunerControlComplete

   237      */

   238     IMPORT_C void RequestTunerControl();

   239 

   240     /**

   241      * Close the tuner and free all memory allocated. Any ongoing playing activity will be stopped,

   242      * control of the tuner will be released, and the hardware will be powered down if no other

   243      * clients need it.

   244      *

   245      * @since S60 3.2

   246      */

   247 	IMPORT_C void Close();

   248 

   249     /**

   250      * Get the capabilities of the FM tuner on the device.

   251      *

   252      * @since S60 3.2

   253      * @param aCaps The capabilities object to fill

   254      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   255      */

   256     IMPORT_C TInt GetCapabilities( TFmTunerCapabilities& aCaps );

   257 

   258     /**

   259      * Enable tuner functions when the device is in offline mode. Client

   260      * should first check the capabilities to see if this feature is supported.

   261      *

   262      * When requested prior to requesting tuner control, this function will succeed with

   263      * KErrNone, however, tuner will only be enabled in offline mode if supported by the

   264      * tuner device.

   265      *

   266      * Tuner functions are disabled in offline mode by default.

   267      *

   268      * @since S60 3.2

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

   270      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   271      */

   272     IMPORT_C TInt EnableTunerInOfflineMode( TBool aEnable );

   273 

   274     /**

   275      * Asynchronous request to set the frequency range. User must be ready to receive

   276      * callback method MrftoSetFrequencyRangeComplete. If not set, it will be defaulted

   277      * to EFmRangeEuroAmerica.

   278      *

   279      * @since S60 3.2

   280      * @param aRange Frequency range

   281      */

   282     IMPORT_C void SetFrequencyRange( TFmRadioFrequencyRange aRange );

   283 

   284     /**

   285      * Cancels an ongoing set frequency range operation, as initiated by a call to

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

   287      *

   288      * Has not effect if no set frequency range operation is ongoing.

   289      *

   290      * @since S60 3.2

   291      */

   292     IMPORT_C void CancelSetFrequencyRange();

   293 

   294     /**

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

   296      * for the returned range. Client should always use the minimum and maximum frequencies returned

   297      * by the tuner device, since it may vary slightly depending on the hardware.

   298      *

   299      * @since S60 3.2

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

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

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

   303      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   304      */

   305     IMPORT_C TInt GetFrequencyRange( TFmRadioFrequencyRange& aRange, TInt& aMinFreq, TInt& aMaxFreq ) const;

   306 

   307     /**

   308      * Asynchronous request to tune the tuner to the speficied frequency (Hz). User must be

   309      * ready to receive callback method MrftoTuneComplete.

   310      *

   311      * @since S60 3.2

   312      * @param aFrequency The frequency to tune to

   313      * @see MRadioFmTunerObserver::MrftoTuneComplete

   314      */

   315     IMPORT_C void SetFrequency( TInt aFrequency );

   316 

   317     /**

   318      * Cancels an ongoing tune operation, as initiated by a call to Tune.

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

   320      *

   321      * Has not effect if no tune operation is ongoing.

   322      *

   323      * @since S60 3.2

   324      */

   325     IMPORT_C void CancelSetFrequency();

   326 

   327     /**

   328      * Get the currently tuned frequency.

   329      *

   330      * @since S60 3.2

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

   332      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   333      */

   334     IMPORT_C TInt GetFrequency( TInt& aFrequency ) const;

   335 

   336     /**

   337      * Asynchronous request to find a radio station, starting from the currently tuned frequency and

   338      * searching in the direction specified (i.e. up or down). User must be ready to receive callback

   339      * method MrftoSeekComplete. The station found is returned in the callback.

   340      *

   341      * If no station is found after a complete loop, seek will stop and return KErrNotfound

   342      * in the callback method and frequency will not change.

   343      *

   344      * @since S60 3.2

   345      * @param aUpwards The direction to search in. Searches upwards if set to ETrue.

   346      * @see MRadioFmTunerObserver::MrftoStationSeekComplete

   347      */

   348     IMPORT_C void StationSeek( TBool aUpwards );

   349 

   350     /**

   351      * Cancels an ongoing station seek operation, as initiated by a call to StationSeek.

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

   353      *

   354 	 * Has not effect if no station seek operation is ongoing.

   355      *

   356      * @since S60 3.2

   357      */

   358     IMPORT_C void CancelStationSeek();

   359 

   360     /**

   361      * Get the signal strenth of the currently tuned frequency.

   362      *

   363      * @since S60 3.2

   364      * @param aSignalStrength On return contains the signal strength.

   365      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   366      */

   367     IMPORT_C TInt GetSignalStrength( TInt& aSignalStrength ) const;

   368 

   369     /**

   370      * Get the maximum possible signal strength of a tuned frequency.

   371      *

   372      * @since S60 3.2

   373      * @param aMaxSignalStrength On return contains the maximum signal strength.

   374      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   375      */

   376     IMPORT_C TInt GetMaxSignalStrength( TInt& aMaxSignalStrength ) const;

   377 

   378     /**

   379      * Get the current frequency's stereo mode (stereo or mono).

   380      *

   381      * @since S60 3.2

   382      * @param aStereo On return, will be ETrue if a stereo signal is currently being received.

   383      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   384      */

   385     IMPORT_C TInt GetStereoMode( TBool& aStereo ) const;

   386 

   387     /**

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

   389      *

   390      * @since S60 3.2

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

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

   393      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   394      */

   395     IMPORT_C TInt ForceMonoReception( TBool aForcedMono );

   396 

   397     /**

   398      * Find out whether reception is forced into monophonic mode or not.

   399      *

   400      * @since S60 3.2

   401      * @param aForcedMono On return, will be ETrue if a forced mono is currently enabled.

   402      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   403      */

   404     IMPORT_C TInt GetForcedMonoReception( TBool& aForcedMono ) const;

   405 

   406     /**

   407      * Set the current squleching (muting in frequencies without reception) setting.

   408      * Squelching is enabled by default.

   409      *

   410      * @since S60 3.2

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

   412      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   413      */

   414     IMPORT_C TInt SetSquelch( TBool aSquelch );

   415 

   416     /**

   417      * Get the current squelching (muting in frequencies without reception) setting.

   418      *

   419      * @since S60 3.2

   420      * @param aSquelch On return, will be ETrue if a squelching is currently enabled.

   421      * @return A standard system error code or FM tuner error (TFmRadioTunerError).

   422      */

   423     IMPORT_C TInt GetSquelch( TBool& aSquelch ) const;

   424 

   425 private:

   426 

   427     /**

   428      * Factory function to create a new instance of the FM tuner.

   429      *

   430      * @since S60 3.2

   431      * @param aRadioSession Reference to radio session

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

   433      * @return A new FM tuner utility object.

   434      */

   435     static CRadioFmTunerUtility* NewL( RRadioSession& aRadioSession, MRadioFmTunerObserver& aObserver );

   436 

   437     virtual ~CRadioFmTunerUtility();

   438 

   439     CRadioFmTunerUtility();

   440 

   441     void ConstructL();

   442 

   443 private: // data

   444 

   445     class CBody;

   446 

   447     /**

   448      * FM tuner utility implementation body

   449      * Own.

   450      */

   451     CBody* iBody;

   452     };

   453 

   454 #endif // C_RADIOFMTUNERUTILITY_H