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:  Header file for Tuner component.

    15 *

    16 */

    17 

    18 

    19 #ifndef TUNER_H

    20 #define TUNER_H

    21 

    22 #include <e32base.h>

    23 #include <MCustomCommand.h>

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

    25 #include <mmf/common/mmfutilities.h>

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

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

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

    29 #include <Mda/Common/audio.h>

    30 class RRadioSession;

    31 

    32 /**

    33 @file

    34 @publishedAll

    35 @prototype

    36 */

    37 /**

    38 The Tuner Capabilities structure defines the capabilities of the tuner

    39 on the device, as retrieved using the function GetCapabilities.

    40 */

    41 class TTunerCapabilities

    42 {

    43 public:

    44     inline TTunerCapabilities();

    45     inline TTunerCapabilities(TUint32 aTunerBands, TUint32 aAdditionalFunctions);

    46 public:

    47     /**

    48     Bitfield (as defined by CMMTunerUtility::TTunerBand) with the bits of the

    49     supported bands set

    50     */

    51     TUint32 iTunerBands;

    52 

    53     /** Tuner Function bit flags - may be extended in future */

    54     enum TTunerFunctions

    55     {

    56         /** Recording of Tuner Audio is possible */

    57         ETunerFunctionRecording                 = 0x01,

    58         /** Tuner can record and play back simultaneously */

    59         ETunerFunctionSimultaneousPlayAndRecord = 0x02,

    60         /** The tuner requires an external antenna (e.g. a headset) to function */

    61         ETunerFunctionRequiresAntenna           = 0x04,

    62         /** CMMRdsTunerUtility supported */

    63         ETunerFunctionRds                       = 0x08,

    64         /** The tuner can be used when the device is in flight mode */

    65         ETunerFunctionAvailableInFlightMode     = 0x10

    66     };

    67 

    68     /** Bitfield (as defined by ETunerFunctions) with the bits of the supported functions set */

    69     TUint32 iAdditionalFunctions;

    70 };

    71 

    72 /**

    73 Class representing a frequency.

    74 */

    75 class TFrequency

    76 {

    77 public:

    78     inline TFrequency();

    79     explicit inline TFrequency(TInt aFrequency);

    80     inline TInt operator==(const TFrequency& aFrequency) const;

    81     inline TInt operator!=(const TFrequency& aFrequency) const;

    82     inline TInt operator> (const TFrequency& aFrequency) const;

    83     inline TInt operator>=(const TFrequency& aFrequency) const;

    84     inline TInt operator< (const TFrequency& aFrequency) const;

    85     inline TInt operator<=(const TFrequency& aFrequency) const;

    86 public:

    87     /**

    88     The Frequency, in Hertz. A TInt is at least 32 bits, giving a maximum frequency

    89     of at least 2.4GHz (i.e. 0x7fffffff Hz)

    90     */

    91     TInt iFrequency;

    92 };

    93 

    94 

    95 class MMMTunerObserver;

    96 class MMMTunerChangeObserver;

    97 class MMMTunerStereoObserver;

    98 class MMMSignalStrengthObserver;

    99 class MMMTunerAudioPlayerObserver;

   100 class MMMTunerAudioRecorderObserver;

   101 class CMMTunerAudioPlayerUtility;

   102 class CMMTunerAudioRecorderUtility;

   103 class CMMTunerScannerUtility;

   104 class CMMRdsTunerUtility;

   105 

   106 /**

   107 The MMF Tuner API is present to allow clients to control

   108 the tuner hardware present on a device.

   109 */

   110 class CMMTunerUtility : public CBase

   111 {

   112     friend class CMMTunerAudioPlayerUtility;

   113     friend class CMMTunerAudioRecorderUtility;

   114     friend class CMMTunerScannerUtility;

   115     friend class CMMRdsTunerUtility;

   116 public:

   117     /** Tuner Band bit flags - may be extended in future */

   118     enum TTunerBand

   119     {

   120         ETunerNoBand            = 0x00,

   121         /** Long Wave - uses frequencies */

   122         ETunerBandLw            = 0x01,

   123         /** Amplitude Modulation or Medium Wave - uses frequencies */

   124         ETunerBandAm            = 0x02,

   125         /** Frequency Modulation, European and American band - uses frequencies */

   126         ETunerBandFm            = 0x04,

   127         /** Frequency Modulation, Japanese band - uses frequencies */

   128         ETunerBandJapaneseFm    = 0x08,

   129         /** Digital Audio Broadcasting - uses channels */

   130         ETunerBandDab           = 0x10,

   131         /** Digital Video Broadcasting */

   132         ETunerBandDvb           = 0x20

   133     };

   134     /**

   135     Search direction enumeration

   136     */

   137     enum TSearchDirection

   138     {

   139         /** Search for stations upwards - i.e. by increasing frequency */

   140         ESearchDirectionUp = 1,

   141         /** Search for stations downwards - i.e. by decreasing frequency */

   142         ESearchDirectionDown

   143     };

   144     /**

   145     The Tuner Access Priority enables clients to correctly identify their needs

   146     when it comes to accessing the tuner. A process must have the MultimediaDD

   147     capability to use priorities greater than ETunerAccessPriorityNormal.

   148     */

   149     enum TTunerAccessPriority

   150     {

   151         /** Radio accessible when device is idle */

   152         ETunerAccessPriorityBackground      = -100,

   153         /** Ordinary application priority */

   154         ETunerAccessPriorityNormal          = 0,

   155         /** Radio is to be used as an alarm sound */

   156         ETunerAccessPriorityAlarm           = 75,

   157         /** System use only */

   158         ETunerAccessPrioritySystem          = 100

   159     };

   160     /**

   161     Bitmasks to indicate what state the tuner is in.

   162     */

   163     enum TTunerState

   164     {

   165         /**

   166         Tuner is active, and can therefore report frequency etc. If this bit is

   167         not set, none of the others should be set.

   168         */

   169         ETunerStateActive       = 0x01,

   170         /** The tuner is playing sound. */

   171         ETunerStatePlaying      = 0x02,

   172         /** The tuner is currently recording. */

   173         ETunerStateRecording    = 0x04,

   174         /** The tuner is currently retuning or searching for a new station. */

   175         ETunerStateRetuning     = 0x08,

   176     };

   177 public:

   178 

   179     /**

   180     Factory function to create a new instance of the Tuner. Tuner access priority

   181     setting is required to ensure that applications such as alarms using the radio

   182     as an alarm sound are not prevented from doing so by other clients. Priority

   183     setting is needed for audio output when accessing the sound device. Tuner is

   184     ready for use on return from this function.

   185 

   186     @param aObserver The observer object for receiving async completion callbacks

   187     @param aTunerIndex An index from 0 to TunersAvailable() - 1 specifying the tuner

   188             device to use.

   189     @param aAccessPriority Tuner access priority value

   190     @leave KErrNoMemory Out of memory

   191     @leave KErrNotFound The specified tuner or tuner controller is not present

   192     @return A pointer and ownership of the fully constructed CMMTunerUtility object

   193     */

   194     IMPORT_C static CMMTunerUtility* NewL(MMMTunerObserver& aObserver,

   195                                           TTunerBand aBand,

   196                                           TInt aTunerIndex,

   197                                           CMMTunerUtility::TTunerAccessPriority aAccessPriority = ETunerAccessPriorityNormal);

   198 

   199     IMPORT_C virtual ~CMMTunerUtility();

   200 

   201 

   202 

   203     /**

   204     Set the current tuner access priority of this client. This priority is used to

   205     arbitrate between multiple tuner clients, determining who get control of the

   206     tuner.

   207 

   208     The platform security capability is MultimediaDD and a client with this capability

   209     is allowed to set the priority in preference to a client with a lower capability.

   210 

   211     @param aAccessPriority The new priority to use.

   212     @capability MultimediaDD

   213     @return A standard system error code.

   214     */

   215     IMPORT_C TInt SetPriority(TTunerAccessPriority aAccessPriority);

   216 

   217     /**

   218     Get the current tuner access priority of this client.

   219 

   220     @param aAccessPriority A variable to which the current priority will be written.

   221     @return A standard system error code.

   222     */

   223     IMPORT_C TInt GetPriority(TTunerAccessPriority& aAccessPriority) const;

   224 

   225 

   226     /**

   227     Get the current state of the tuner.

   228 

   229     @param aState A variable to set with the current state. Bits set according to

   230            TTunerState.

   231     @return A standard system error code.

   232     */

   233     IMPORT_C TInt GetState(TUint32& aState) const;

   234 

   235     /**

   236     Indicates if the external antenna is currently attached or not. The tuner

   237     capabilties should be queried to determine if the external antenna is required

   238     to use the tuner or not; A value of false returned here does not necessarily

   239     imply that the tuner cannot be used.

   240 

   241     @param aAttached When this function returns, this will contain ETrue if and only

   242            if an external antenna is attached.

   243     @return A standard system error code.

   244     */

   245     IMPORT_C TInt IsAntennaAttached(TBool& aAttached);

   246 

   247     /**

   248     Indicates if the device is currently in 'flight mode' or not. The tuner

   249     capabilities should be queried to determine in the tuner can be used  in flight

   250     mode or not.

   251 

   252     @param aFlightMode On return, this will have been set to ETrue if and only if

   253             the device is in flight mode.

   254     @return A standard system error code.

   255     */

   256     IMPORT_C TInt GetFlightMode(TBool& aFlightMode) const;

   257 

   258     /**

   259     Tune the tuner to the required frequency specified in Hertz. This is an asynchronous

   260     command and will result in a callback to MToTuneComplete or MToTunerError.

   261 

   262     If the session does not currently have control of the tuner, a request for control

   263     will be made. If control of the tuner is granted, a callback to MToTunerControlGranted

   264     will occur. If not, there will be a callback to MtoTunerError with error value

   265     KErrAccessDenied.

   266 

   267     Once control of the tuner has been granted, it will be retained until either a

   268     call to ReleaseTunerControl, or the session is preempted in which case there

   269     will be a callback to MToTunerError with error value KErrAccessDenied.

   270 

   271     @param aFrequency The frequency to tune to

   272     @param aBand The band to which aFrequency belongs

   273     */

   274     IMPORT_C void Tune(TFrequency aFrequency);

   275 

   276     /**

   277     Find a radio station, starting at the start frequency and searching in the

   278     direction specified (i.e. Up or down) the search is limited to the specified

   279     band.  If the session does not currently have control of the tuner, a request

   280     for control will be made. If control of the tuner is granted, a callback to

   281     MToTunerControlGranted will occur. If not, there will be a callback to MToTunerError

   282     with error value KErrAccessDenied.

   283 

   284     Once control of the tuner has been granted, it will be retained until either a

   285     call to ReleaseTunerControl, or the session is preempted in which case there

   286     will be a callback to MToTunerError with error value KErrAccessDenied.

   287 

   288     A callback to MToTuneComplete will occur if the Seek is successful.

   289 

   290     @param aBand The band

   291     @param aSearchDirect The direction to search in

   292     @param aCircularSeek If set to ETrue the station seek will loop back to the other

   293            end of the band once the end of the band has been reached. (Defaults to ETrue)

   294            If not set reaching the end of the band without finding a station will result

   295            in a callback to MToTuneComplete with error KErrNotFound.

   296     */

   297     IMPORT_C void StationSeek(TSearchDirection aSearchDirection);

   298 

   299     /**

   300     Cancels an ongoing retune operation, as initiated by a call to Tune or StationSeek.

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

   302 

   303     Has not affect if no tune or seek operation is ongoing.

   304     */

   305     IMPORT_C void CancelRetune();

   306 

   307     /**

   308     Makes a synchronous request for control of the tuner. If this method returns

   309     KErrNone, control of the tuner has been granted. Control of the tuner is kept

   310     until it is explically released using ReleaseTunerControl, or it is revoked

   311     in which case a callback to MToTunerError with an error of KErrAccessDenied

   312     will occur.

   313 

   314     If this method returns with KErrAccessDenied, a request to recieve a

   315     notifiaction when control could be granted can be made using

   316     NotifyTunerControl.

   317 

   318     Note that methods that require control of the tuner (such as Tune) will make

   319     a request for control themselves if control has not already been granted.

   320 

   321     @return A standard system error code. If control was granted, KErrNone, and if

   322             control was denied KErrAccessDenied.

   323     */

   324     IMPORT_C TInt RequestTunerControl();

   325 

   326     /**

   327     Makes an asyncronous request for control of the tuner. This method should be

   328     called after an control of the tuner has been denied to receive a notification

   329     when control of the tuner can be granted. A callback to MToTunerControlGranted

   330     will occur in this event.

   331     */

   332     IMPORT_C TInt NotifyTunerControl();

   333 

   334     /**

   335     Release control of the tuner, allowing other clients to tune it. Change

   336     notifications may still be received. A request for control of the tuner can be

   337     made again by calling RequestTunerControl, or any methods that require control

   338     of the tuner.

   339     */

   340     IMPORT_C void ReleaseTunerControl();

   341 

   342     /**

   343     Release the tuner. Any ongoing playing or recording activity will be stopped,

   344     control of the tuner will be released, and the hardware will be powered down if

   345     no other clients need it.

   346     */

   347     IMPORT_C void Close();

   348 

   349     /**

   350     Retrieve the current frequency that the tuner is tuned to

   351 

   352     @param aFrequency The variable to set to the current frequency,

   353     -1 if channels are in use

   354     @param aBand The variable used to set the current band.

   355     @return A standard system error code

   356     */

   357     IMPORT_C TInt GetFrequency(TFrequency& aFrequency) const;

   358 

   359     /**

   360     Retrieve the signal strenth of the currently tuned signal

   361 

   362     @param aSignalStrength Variable into which the signal strength will be written.

   363     @return A standard system error code

   364     */

   365     IMPORT_C TInt GetSignalStrength(TInt& aSignalStrength) const;

   366 

   367     /**

   368     Get the maximum possible signal strength of a tuned signal.

   369 

   370     @param aMaxSignalStrength A variable that will have the maximun signal strength

   371             written to.

   372     @return A standard system error code

   373     */

   374     IMPORT_C TInt GetMaxSignalStrength(TInt& aMaxSignalStrength) const;

   375 

   376     /**

   377     Request notifications when the signal strength changes. Due to the potentially

   378     short intervals at which the signal strength may change at, notifications will

   379     only be sent when a relatively large change occurrs. This should allow a visual

   380     display of signal strength to be maintained fairly accurately.

   381 

   382     The first signal strength notification will be sent immediately after this

   383     request.

   384 

   385     @param aObserver The object which will receive notifications of signal strength

   386             changes.

   387     @return A standard system error code

   388     */

   389     IMPORT_C TInt NotifySignalStrength(MMMSignalStrengthObserver& aObserver);

   390 

   391     /**

   392     Cancel an outstanding NotifySignalStrength request.

   393     */

   394     IMPORT_C void CancelNotifySignalStrength();

   395 

   396     /**

   397     Find out if the current signal is being received in stereo or not.

   398 

   399     @param aStereo On return, will be ETrue if and only if a stereo signal is

   400            currently being received.

   401     */

   402     IMPORT_C TInt IsStereoSignal(TBool& aStereo);

   403 

   404     /**

   405     Request notifications when stereo reception is lost/restored.

   406 

   407     @param aObserver The object requiring notification when a stereo signal is lost

   408            or restored. The first notification will occur immediately.

   409     @return A standard system error code

   410     */

   411     IMPORT_C TInt NotifyStereoChange(MMMTunerStereoObserver& aObserver);

   412 

   413     /**

   414     Cancels a stereo change notification request.

   415     */

   416     IMPORT_C void CancelNotifyStereoChange();

   417 

   418     /**

   419     Indicates whether the reception should be forced into monophonic mode.

   420 

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

   422            signal is available. If EFalse, a stereo signal will be received when

   423            possible.

   424     @return A standard system error code.

   425     */

   426     IMPORT_C TInt ForceMonoReception(TBool aMono);

   427 

   428     /**

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

   430 

   431     @param aMono This will be set to ETrue if all reception is forced to be mono. If

   432            this is EFalse, this does not imply that stereo reception is currently

   433            available.

   434     @return A standard system error code.

   435     */

   436     IMPORT_C TInt GetForcedMonoReception(TBool& aMono) const;

   437 

   438     /**

   439     Sets the current squleching (muting in frequencies without reception) setting.

   440 

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

   442     @return KErrNone if successful, else a system wide error code.

   443     */

   444     IMPORT_C TInt SetSquelch(TBool aEnabled);

   445 

   446     /**

   447     Gets the current squleching (muting in frequencies without reception) setting.

   448 

   449     @param aEnabled This will be set to ETrue if squelching is enabled, EFalse otherwise.

   450     @return KErrNone if successful, else a system wide error code.

   451     */

   452     IMPORT_C TInt GetSquelch(TBool& aEnabled) const;

   453 

   454     /**

   455     Get the capabilities of the tuner on the device

   456 

   457     @param aCaps The capabilities object to fill

   458     @return A standard system error code

   459     */

   460     IMPORT_C TInt GetCapabilities(TTunerCapabilities& aCaps) const;

   461 

   462     /**

   463     Get the frequency range (in Hertz) of the specified band.

   464     This function should be used to enquire the frequency range

   465     of the bands that GetCapabilities reports as supported.

   466 

   467     @param aBand The band to query

   468     @param aBottomFrequency The variable to set to the lowest frequency allowed

   469     @param aTopFrequency The variable to set to the highest frequency allowed

   470     @return A standard system error code

   471     */

   472     IMPORT_C TInt GetFrequencyBandRange(TFrequency& aBottomFrequency, TFrequency& aTopFrequency);

   473 

   474     /**

   475     Request to be notified when the tuned frequency or channel changes, or when the

   476     tuner changes state (e.g. starts playing or recording)

   477 

   478     @param aObserver The object wishing to receive tuning change events

   479     @return A standard system error code

   480     */

   481     IMPORT_C TInt NotifyChange(MMMTunerChangeObserver& aObserver);

   482 

   483     /**

   484     Cancel request to be notified when the tuned frequency or channel changes

   485     */

   486     IMPORT_C void CancelNotifyChange();

   487 

   488     /**

   489     Send a synchronous custom command to the tuner.

   490 

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

   492         on the interface defined by the first IPC argument

   493     @param aArgs The IPC arguments to send to the tuner. The first of these

   494         arguments must be the UID of the interface within the tuner to which the

   495         command is destined, represented as an integer. Failure to set the first

   496         argument properly will result in the command completing with

   497         KErrNotSupported at best, but possibly  the client being panicked.

   498     @return A standard system error code

   499     */

   500     IMPORT_C TInt CustomCommandSync(TInt aFunction, const TIpcArgs& aArgs);

   501 

   502     /**

   503     Send an asynchronous custom command to the tuner.

   504 

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

   506         on the interface defined by the first IPC argument

   507     @param aArgs The IPC arguments to send to the tuner. The first of these

   508         arguments must be the UID of the interface within the tuner to which the

   509         command is destined, represented as an integer. Failure to set the first

   510         argument properly will result in the command completing with

   511         KErrNotSupported at best, but possibly  the client being panicked.

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

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

   514         dependent on the interface.

   515     */

   516     IMPORT_C void CustomCommandAsync(TInt aFunction, const TIpcArgs& aArgs, TRequestStatus& aStatus);

   517 

   518     /**

   519     Get the Tuner Player Utility

   520 

   521     @param aAccessPriority A variable to which the current priority will be written.

   522     @return A standard system error code.

   523     */

   524     IMPORT_C CMMTunerAudioPlayerUtility* TunerPlayerUtilityL(MMMTunerAudioPlayerObserver& aObserver) ;

   525     /**

   526     Get the Tuner Recorder Utility

   527 

   528     @param aAccessPriority A variable to which the current priority will be written.

   529     @return A standard system error code.

   530     */

   531     IMPORT_C CMMTunerAudioRecorderUtility* TunerRecorderUtilityL(MMMTunerAudioRecorderObserver& aObserver) ;

   532 

   533     /**

   534     Get the Tuner Scanner Utility

   535 

   536     @param aAccessPriority A variable to which the current priority will be written.

   537     @return A standard system error code.

   538     */

   539     IMPORT_C CMMTunerScannerUtility* TunerScannerUtilityL() ;

   540 

   541     /**

   542     Get the Tuner Rds Utility

   543 

   544     @param aAccessPriority A variable to which the current priority will be written.

   545     @return A standard system error code.

   546     */

   547     IMPORT_C CMMRdsTunerUtility* TunerRdsUtilityL() ;

   548 

   549 private:

   550     CMMTunerUtility();

   551 protected:

   552     class CBody;

   553 private:

   554     CBody* iBody;

   555 };

   556 

   557 /**

   558 The Tuner Observer mixin class defines asynchronous

   559 event completion function callbacks

   560 */

   561 class MMMTunerObserver

   562 {

   563 public:

   564     /**

   565     Tune complete event. This event is asynchronous

   566     and is received after a call to the Tune method.

   567 

   568     @param aError A standard system error

   569     */

   570     virtual void MToTuneComplete(TInt aError) = 0;

   571 

   572 };

   573 

   574 /**

   575 The Tuner Change Observer mixin class defines the interface via which

   576 notification for changes to the tuned frequency, channel and other tuner

   577 state can be received. A client interested in these notifications

   578 should call the function CMMTunerUtility::NotifyChange.

   579 */

   580 class MMMTunerChangeObserver

   581 {

   582 public:

   583     /**

   584     Called when the tuned frequency changes

   585 

   586     @param aOldFrequency The frequency in use before the change

   587     @param aNewFrequency The new tuned frequency

   588     */

   589     virtual void MTcoFrequencyChanged(const TFrequency& aOldFrequency, const TFrequency& aNewFrequency) = 0;

   590 

   591     /**

   592     Called when the state of the tuner changes.

   593 

   594     @param aOldState The old state. Bits are set according to TTunerState.

   595     @param aNewState The new state. Bits are set according to TTunerState.

   596     */

   597     virtual void MTcoStateChanged(const TUint32& aOldState, const TUint32& aNewState) = 0;

   598 

   599     /**

   600     This function is called when an external antenna is detached from the device.

   601     This does not necessarily indicate that the tuner can no longer be used; the

   602     capabilities of the tuner indicate if the external antenna is required in order

   603     to use the tuner.

   604     */

   605     virtual void MTcoAntennaDetached() = 0;

   606 

   607     /**

   608     This function is called when an external antenna is attached to the device. If

   609     the antenna is required to use the tuner, this indicates that the tuner can be

   610     used again.

   611     */

   612     virtual void MTcoAntennaAttached() = 0;

   613 

   614     /**

   615     This function is called when the device enters or leaves flight mode. If the tuner

   616     cannot be used in flight mode when the device enters this mode, this indicates

   617     that the tuner can no longer be used; the capabilities of the tuner indicate if

   618     it can be used in flight mode or not.

   619 

   620     @param aFlightMode ETrue if the device has just entered flight mode, EFalse if

   621             flight mode has just been left.

   622     */

   623     virtual void FlightModeChanged(TBool aFlightMode) = 0;

   624 };

   625 

   626 /**

   627 The stereo observer mixin class defines the interface by which clients can be

   628 notified when a stereo signal is received/lost. An interested client should call

   629 the function CMMTunerUtility::NotifyStereoChange.

   630 */

   631 class MMMTunerStereoObserver

   632 {

   633 public:

   634     /**

   635     Called when stereo reception is lost/restored.

   636 

   637     @param aStereo If true, indicates that stereo reception has just been restored.

   638            If false, indicates that stereo reception has just been lost.

   639     */

   640     virtual void MTsoStereoReceptionChanged(TBool aStereo) = 0;

   641 

   642     /**

   643     Called when a client enables/disabled forced mono reception.

   644 

   645     @param aForcedMono ETrue if reception is forced to be mono, even when a stereo

   646            signal is available.

   647     */

   648     virtual void MTsoForcedMonoChanged(TBool aForcedMono) = 0;

   649 };

   650 

   651 /**

   652 This mixin class should be derived from by clients wishing to receive

   653 notifications when the signal strength changes. Such a client should call

   654 function CMMTunerUtility::NotifySignalStrength.

   655 */

   656 class MMMSignalStrengthObserver

   657 {

   658 public:

   659     /**

   660     Callback indicating that the signal strength has changed by an amount meriting

   661     a notification.

   662 

   663     @param aNewSignalStrength The new signal strength.

   664     */

   665     virtual void MssoSignalStrengthChanged(TInt aNewSignalStrength) = 0;

   666 };

   667 

   668 

   669 class MMMAudioResourceNotificationCallback;

   670 

   671 /**

   672 The Tuner Audio Player Utility is used to initiate and control playback of audio

   673 from the tuner.

   674 */

   675 class CMMTunerAudioPlayerUtility : public CBase, public MCustomCommand

   676 {

   677     friend class CMMTunerUtility::CBody;

   678 public:

   679 

   680     IMPORT_C ~CMMTunerAudioPlayerUtility();

   681 

   682     /**

   683     Set-up the API for playing the output from tuner to the speaker asynchronously.

   684     Calls MMMTunerAudioPlayerObserver::MTapoInitializeComplete on completion. This must be

   685     called before Play.

   686 

   687     @param aPriority Sound device priority value

   688     @param aPref Sound device priority preference value

   689     */

   690     IMPORT_C void InitializeL(TInt aAudioPriority = EMdaPriorityNormal, TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality);

   691 

   692     /**

   693     Start playback of the tuner output. To stop playback, call Mute, or Stop if

   694     play will not need to be restarted. InitializeL() must have already been

   695     called, and a callback to MTapoInitializeComplete with an error of KErrNone must

   696     have occurred; if this is not the case, this raises a TunerAudioPlay 1 panic.

   697     */

   698     IMPORT_C void Play();

   699 

   700     /**

   701     Mute or unmute playback.

   702 

   703     Raises a TunerAudioPlay 1 panic if the player is not properly initialized.

   704 

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

   706     @return A standard system error code

   707     */

   708     IMPORT_C TInt Mute(TBool aMute);

   709 

   710     /**

   711     Stop playback, and release the output device for use by other clients

   712 

   713     Raises a TunerAudioPlay 1 panic if the player is not properly initialized.

   714 

   715     Playback should already be under way.

   716     */

   717     IMPORT_C void Stop();

   718 

   719     /**

   720     Set the current audio priority. This priority is used to arbitrate

   721     between multiple audio sources trying to access the audio hardware.

   722 

   723     @param aPriority A priority between EMdaPriorityMin and EMdaPriorityMax

   724     @param aPref Time vs Quality priority preferences, enumerated in TMdaPriorityPreference

   725     @return A standard system error code

   726     */

   727     IMPORT_C TInt SetPriority(TInt aPriority, TMdaPriorityPreference aPref);

   728 

   729     /**

   730     Get the current audio priority. This is used to arbitrate between simultaneous

   731     accesses to the sound hardware.

   732 

   733     @param aPriority A priority between EMdaPriorityMin and EMdaPriorityMax to return

   734     @param aPref Time vs Quality priority preferences to return, enumerated in TMdaPriorityPreference

   735     @return A standard system error code

   736     */

   737     IMPORT_C TInt GetPriority(TInt& aPriority, TMdaPriorityPreference& aPref) const;

   738 

   739     /**

   740     Set the volume to the specified level

   741 

   742     Raises a TunerAudioPlay 1 panic if the player is not properly initialized.

   743 

   744     @param aVolume The volume level to set

   745     @return A standard system error code

   746     */

   747     IMPORT_C TInt SetVolume(TInt aVolume);

   748 

   749     /**

   750     Return the current volume

   751 

   752     @param aVolume The variable to set to the current volume

   753     @return A standard system error code

   754     */

   755     IMPORT_C TInt GetVolume(TInt& aVolume) const;

   756 

   757     /**

   758     Define a volume ramp, aRampInterval defining

   759     the interval between valid volume settings

   760 

   761     Raises a TunerAudioPlay 1 panic if the player is not properly initialized.

   762 

   763     @param aRampInterval The time interval over which the volume

   764     should be increased from zero to the current volume setting

   765     @return A standard system error code

   766     */

   767     IMPORT_C TInt SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampInterval);

   768 

   769     /**

   770     Return the maximum volume supported

   771 

   772     @return The maximum volume setting permitted

   773     */

   774     IMPORT_C TInt MaxVolume() const;

   775 

   776     /**

   777     Set the stereo balance between left and right channels

   778 

   779     Raises a TunerAudioPlay 1 panic if the player is not properly initialized.

   780 

   781     @param aBalance The balance value to set - must be between

   782     KMMFBalanceMaxLeft and KMMFBalanceMaxRight

   783     @return A standard system error code

   784     */

   785     IMPORT_C TInt SetBalance(TInt aBalance = KMMFBalanceCenter);

   786 

   787     /**

   788     Return the current stereo balance

   789 

   790     @param aBalance The variable to set to the current balance

   791     @return A standard system error code

   792     */

   793     IMPORT_C TInt GetBalance(TInt& aBalance) const;

   794 

   795     /**

   796     Register for audio resource notifications, in the event that the audio resource is lost due to pre-emption

   797     by a higher priority audio client.

   798     */

   799     IMPORT_C TInt RegisterAudioResourceNotification(MMMAudioResourceNotificationCallback& aCallback, TUid aNotificationEventUid, const TDesC8* aNotificationRegistrationData = NULL);

   800 

   801     /**

   802     Cancel an outstanding audio resource notification.

   803     */

   804     IMPORT_C void CancelRegisterAudioResourceNotification(TUid aNotificationEventId);

   805 

   806     /**

   807     Returns the controller implementation information associated with the current controller, if any.

   808 

   809     @return The controller implementation structure associated with the controller

   810     @leave KErrNotFound if no controller is in use.

   811     */

   812     IMPORT_C const CMMFControllerImplementationInformation& ControllerImplementationInformationL();

   813 

   814     /**

   815     Send a synchronous custom command to the playback controller, if ones exists.

   816 

   817     @param aDestination The destination of the message, consisting of the uid of

   818             the interface of this message

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

   820             on the interface defined in the aDestination parameter

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

   822             framework. The exact contents of the data are dependent on the

   823             interface being called. Can be KNullDesC8.

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

   825             framework. The exact contents of the data are dependent on the

   826             interface being called. Can be KNullDesC8.

   827     @return A standard system error code

   828     */

   829     IMPORT_C TInt CustomCommandSync(

   830         const TMMFMessageDestinationPckg& aDestination,

   831         TInt aFunction,

   832         const TDesC8& aDataTo1,

   833         const TDesC8& aDataTo2);

   834 

   835     /**

   836     Send a synchronous custom command to the playback controller, if ones exists.

   837 

   838     @param aDestination The destination of the message, consisting of the uid of

   839             the interface of this message

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

   841             on the interface defined in the aDestination parameter

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

   843             framework. The exact contents of the data are dependent on the

   844             interface being called. Can be KNullDesC8.

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

   846             framework. The exact contents of the data are dependent on the

   847             interface being called. Can be KNullDesC8.

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

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

   850     @return A standard system error code

   851     */

   852     IMPORT_C TInt CustomCommandSync(

   853         const TMMFMessageDestinationPckg& aDestination,

   854         TInt aFunction,

   855         const TDesC8& aDataTo1,

   856         const TDesC8& aDataTo2,

   857         TDes8& aDataFrom);

   858 

   859     /**

   860     Send an asynchronous custom command to the playback controller, if ones exists.

   861 

   862     @param aDestination The destination of the message, consisting of the uid of

   863             the interface of this message

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

   865             on the interface defined in the aDestination parameter

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

   867             framework. The exact contents of the data are dependent on the

   868             interface being called. Can be KNullDesC8.

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

   870             framework. The exact contents of the data are dependent on the

   871             interface being called. Can be KNullDesC8.

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

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

   874             dependent on the interface.

   875     */

   876     IMPORT_C void CustomCommandAsync(

   877         const TMMFMessageDestinationPckg& aDestination,

   878         TInt aFunction,

   879         const TDesC8& aDataTo1,

   880         const TDesC8& aDataTo2,

   881         TRequestStatus& aStatus);

   882 

   883     /**

   884     Send an asynchronous custom command to the playback controller, if ones exists.

   885 

   886     @param aDestination The destination of the message, consisting of the uid of

   887             the interface of this message

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

   889             on the interface defined in the aDestination parameter

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

   891             framework. The exact contents of the data are dependent on the

   892             interface being called. Can be KNullDesC8.

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

   894             framework. The exact contents of the data are dependent on the

   895             interface being called. Can be KNullDesC8.

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

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

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

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

   900             dependent on the interface.

   901     */

   902     IMPORT_C void CustomCommandAsync(

   903         const TMMFMessageDestinationPckg& aDestination,

   904         TInt aFunction,

   905         const TDesC8& aDataTo1,

   906         const TDesC8& aDataTo2,

   907         TDes8& aDataFrom,

   908         TRequestStatus& aStatus);

   909 

   910 protected:

   911     /**

   912     Factory function to create a new Tuner Audio Player utility. Note that only one audio player

   913     utility may be created per instance of CMMTunerUtility. Multiple instances will result in an

   914     error of KErrAlreadyExists when InitializeL() is called.

   915 

   916     @param aTuner The tuner object which this utility will play the audio from.

   917     @param aObserver The observer of the player utility to receive asychronous completion and

   918             notifiction callbacks.

   919     @leave KErrNoMemory Out of memory

   920     @leave KErrNotSupported If the given tuner doesn't support audio playback.

   921     @return A new tuner audio player utility.

   922     */

   923     static CMMTunerAudioPlayerUtility* NewL(CMMTunerUtility& aTuner, RRadioSession& aRadioSession, MMMTunerAudioPlayerObserver& aObserver);

   924 

   925 private:

   926     CMMTunerAudioPlayerUtility();

   927 private:

   928     class CBody;

   929     CBody* iBody;

   930 };

   931 

   932 class MMMTunerAudioPlayerObserver

   933 {

   934 public:

   935     /**

   936     The TEvent enumeration is used to indicate which type of event is being sent to the client.

   937     Each event will be associated with an error code and potentially some addition information,

   938     and will be passed to the client via method MTapoPlayEvent().

   939     */

   940     enum TEventType

   941     {

   942         /** An event relating to the tuner itself. Any error other than KErrNone associated

   943         with this event type may indicate that the tuner cannot be used anymore.

   944 

   945         No additional information is associated with this type of event. */

   946         ETunerEvent,

   947         /**

   948         An event relating to audio playback.

   949 

   950         No additional information is associated with this type of event.

   951         */

   952         EAudioEvent

   953     };

   954 public:

   955     /**

   956     Initialize complete event. This event is asynchronous and is received after

   957     a call to CMMTunerAudioPlayerUtility::InitializeL().

   958 

   959     @param aError A standard system error

   960     */

   961     virtual void MTapoInitializeComplete(TInt aError) = 0;

   962 

   963     /**

   964     Passes an asychronous event to the tuner client.

   965 

   966     @param aEvent The type of event. See enumeration MMMTunerAudioPlayerObserver::TEventType

   967             for more information about when the event types mean.

   968     @param aError An error code associated with the event.

   969     @param aAdditionalInfo Any additional information associated with the event, or NULL if

   970             no such additional information exists.

   971     */

   972     virtual void MTapoPlayEvent(TEventType aEvent, TInt aError, TAny* aAdditionalInfo) = 0;

   973 };

   974 

   975 /**

   976 This class is used to perform recording of audio from the tuner. Many of the methods

   977 in this class have identical functionality to similarly names functions in class

   978 CMdaAudioRecorderUtility.

   979 */

   980 class CMMTunerAudioRecorderUtility : public CBase

   981 {

   982     friend class CMMTunerUtility::CBody;

   983 public:

   984 

   985     IMPORT_C ~CMMTunerAudioRecorderUtility();

   986 

   987     /**

   988     Initialize for recording from the tuner to the specified file

   989     asynchronously. Calls MMMTunerAudioRecorderObserver::MTaroInitializeComplete on completion

   990 

   991     @param aRecordFilename The name of the file to create, if necessary, and record to

   992     @param "aDestinationDataType" Data type for recording

   993     @param "aControllerUid" The Uid of the controller to use for recording

   994     @param "aDestinationFormatUid" Uid of record format

   995     @param aPriority Sound device priority value

   996     @param aPref Sound device priority preference value

   997     */

   998     IMPORT_C void InitializeL(const TDesC& aRecordFilename,

   999                               TFourCC aDestinationDataType = KFourCCNULL,

  1000                               TUid aControllerUid=KNullUid,

  1001                               TUid aDestinationFormatUid=KNullUid,

  1002                               TInt aAudioPriority = EMdaPriorityNormal,

  1003                               TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality);

  1004 

  1005     /**

  1006     Initialize for recording from the tuner to the specified descriptor

  1007     asynchronously. Calls MMMTunerAudioRecorderObserver::MTaroInitializeComplete on completion

  1008 

  1009     @param aRecordDescriptor The descriptor to record to

  1010     @param "aDestinationDataType" Data type for recording

  1011     @param "aControllerUid" The Uid of the controller to use for recording

  1012     @param "aDestinationFormatUid" Uid of record format

  1013     @param aPriority Sound device priority value

  1014     @param aPref Sound device priority preference value

  1015     */

  1016     IMPORT_C void InitializeL(TDes8& aRecordDescriptor,

  1017                               TFourCC aDestinationDataType = KFourCCNULL,

  1018                               TUid aControllerUid=KNullUid,

  1019                               TUid aDestinationFormatUid=KNullUid,

  1020                               TInt aAudioPriority = EMdaPriorityNormal,

  1021                               TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality);

  1022 

  1023     /**

  1024     Return a list of the supported data types for the record destination

  1025     @param "aSupportedDataTypes" list of four character codes, representing supported data

  1026         encodings for the record destination.

  1027     @leaves Can leave with one of the system-wide error codes

  1028     */

  1029     IMPORT_C void GetSupportedDestinationDataTypesL(RArray<TFourCC>& aSupportedDataTypes) const;

  1030 

  1031     /**

  1032     Set the data type of the destination audio clip

  1033     @param "aDataType" four character code, representing the encoding of the destination audio clip

  1034     @leaves Can leave with one of the system-wide error codes

  1035     */

  1036     IMPORT_C void SetDestinationDataTypeL(TFourCC aDataType);

  1037 

  1038     /**

  1039     Return the data type of the destination audio clip

  1040     @returns four character code, representing the encoding of the destination audio clip

  1041     @leaves Can leave with one of the system-wide error codes

  1042     */

  1043     IMPORT_C TFourCC DestinationDataTypeL() const;

  1044 

  1045     /**

  1046     Set the bit rate for recording

  1047     @param "aBitRate" destination bit rate in bits/second

  1048     @leaves Can leave with one of the system-wide error codes

  1049     */

  1050     IMPORT_C void SetDestinationBitRateL(TUint aBitRate);

  1051 

  1052     /**

  1053     Return the recording bit rate

  1054     @returns destination bit rate in bits/second

  1055     @leaves Can leave with one of the system-wide error codes

  1056     */

  1057     IMPORT_C TUint DestinationBitRateL() const;

  1058 

  1059     /**

  1060     Return a list of the supported bit rates for recording

  1061     @param "aSupportedBitRates" List of bit rates supported for the record

  1062            destination

  1063     @leaves Can leave with one of the system-wide error codes

  1064     */

  1065     IMPORT_C void GetSupportedBitRatesL(RArray<TUint>& aSupportedBitRates) const;

  1066 

  1067     /**

  1068     Set the sample rate for the record destination

  1069     @param "aSampleRate" The sample rate of the record destination

  1070     @leaves Can leave with one of the system-wide error codes

  1071     */

  1072     IMPORT_C void SetDestinationSampleRateL(TUint aSampleRate);

  1073 

  1074     /**

  1075     Return the sample rate of the record destination

  1076     @returns The sample rate of the record destination

  1077     @leaves Can leave with one of the system-wide error codes

  1078     */

  1079     IMPORT_C TUint DestinationSampleRateL() const;

  1080 

  1081     /**

  1082     Get a list of supported recording sample rates.

  1083     @param "aSupportedSampleRates" List of the sample rates that are supported for

  1084            recording

  1085     @leaves Can leave with one of the system-wide error codes

  1086     */

  1087     IMPORT_C void GetSupportedSampleRatesL(RArray<TUint>& aSupportedSampleRates) const;

  1088 

  1089     /**

  1090     Set the format of the audio clip. This can only be done if the audio clip does not

  1091     exist

  1092 

  1093     @param "aFormatUid" Uid of the audio clip format

  1094     @leaves KErrAlreadyExists if the clip already exists and the format is different

  1095      from the existing format, or can leave with one of the system-wide error codes

  1096     */

  1097     IMPORT_C void SetDestinationFormatL(TUid aFormatUid);

  1098 

  1099     /**

  1100     Return the format of the audio clip

  1101     @returns Uid of the audio clip format

  1102     @leaves Can leave with one of the system-wide error codes

  1103     */

  1104     IMPORT_C TUid DestinationFormatL() const;

  1105 

  1106     /**

  1107     Set the number of channels for the recorded audio clip

  1108     @param "aNumberOfChannels" The number of channels to record

  1109     @leaves Can leave with one of the system-wide error codes

  1110     */

  1111     IMPORT_C void SetDestinationNumberOfChannelsL(TUint aNumberOfChannels);

  1112 

  1113     /**

  1114     Return the number of channels in audio clip

  1115     @returns number of channels supported by audio clip

  1116     @leaves Can leave with one of the system-wide error codes

  1117     */

  1118     IMPORT_C TUint DestinationNumberOfChannelsL() const;

  1119 

  1120     /**

  1121     Return a list of the supported number of channels for recording

  1122     @param "aSupportedNumChannels" List of the number of channels supported for

  1123             recording

  1124     @leaves Can leave with one of the system-wide error codes

  1125     */

  1126     IMPORT_C void GetSupportedNumberOfChannelsL(RArray<TUint>& aSupportedNumChannels) const;

  1127 

  1128     /** Start recording of the tuner output */

  1129     IMPORT_C void RecordL();

  1130 

  1131     /**

  1132     Pause recording. Recording can be resumed with another call to Record.

  1133 

  1134     @return A standard system error code