1 /*

     2 * Copyright (c) 2009 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:

    15 *

    16 */

    17 

    18 

    19 #ifndef CRADIOENGINE_H_

    20 #define CRADIOENGINE_H_

    21 

    22 // User includes

    23 #include "cradioroutableaudio.h"

    24 #include "radioenginedef.h"

    25 #include "radioengine.hrh"

    26 

    27 // Forward declarations

    28 class MRadioEngineInitializer;

    29 class CRadioAudioRouter;

    30 class CRadioSettings;

    31 class MRadioApplicationSettings;

    32 class MRadioEngineSettings;

    33 class CRadioSystemEventCollector;

    34 class CRadioPubSub;

    35 class CRadioRepositoryManager;

    36 class MRadioPresetSettings;

    37 class MRadioSettingsSetter;

    38 class MRadioScanObserver;

    39 class MRadioEngineObserver;

    40 class MRadioRdsReceiver;

    41 

    42 /**

    43  * Convenience class to handle engine startup and the ownership of the related classes

    44  */

    45 NONSHARABLE_CLASS( CRadioEngine ) : public CRadioRoutableAudio

    46     {

    47 public:

    48 

    49     /**

    50      * Starts the radio engine initialization.

    51      * Asks the given initializer to create the member variables

    52      */

    53     IMPORT_C static CRadioEngine* NewL( MRadioEngineInitializer& aInitializer );

    54 

    55     IMPORT_C ~CRadioEngine();

    56 

    57     /**

    58      * Returns a reference to the audio router

    59      *

    60      * @return  Reference to the audio router

    61      */

    62     virtual CRadioAudioRouter& AudioRouter() const = 0;

    63 

    64     /**

    65      * Returns the system event collector

    66      *

    67      * @return  The system event collector

    68      */

    69     virtual CRadioSystemEventCollector& SystemEventCollector() const = 0;

    70 

    71     /**

    72      * Returns a reference to the application settings

    73      *

    74      * @return  Reference to the application settings

    75      */

    76     virtual CRadioSettings& Settings() const = 0;

    77 

    78     /**

    79      * Returns a reference to the publish & subscribe handler

    80      *

    81      * @return  Reference to the publish & subscribe handler

    82      */

    83     virtual CRadioPubSub* PubSub() const = 0;

    84 

    85     /**

    86      * Determines radio region

    87      */

    88     virtual TRadioRegion DetermineRegion() = 0;

    89 

    90     /**

    91      * ( Re )initializes the radio.

    92      *

    93      * @param aRegionId Region id

    94      * @param aPubSub   Pointer to Publish&Subscribe object

    95      */

    96     virtual void InitRadioL( TInt aRegionId, CRadioPubSub* aPubSub = 0 ) = 0;

    97 

    98     /**

    99      * Has the radio been initialized

   100      *

   101      * @return ETrue if radio is initialized, otherwise EFalse

   102      */

   103     virtual TBool RadioInitialized() const = 0;

   104 

   105     /**

   106      * Sets the state for radio audio

   107      * This is the public interface to manage radio power state

   108      * This method should be called before radio can turn itself on

   109      *

   110      * @param aEnable ETrue if radio audio can be played,

   111      *                EFalse if audio should be disabled

   112      * @param aDelay  ETrue if radio is played/disabled with delay

   113      *                EFalse if radio is played/disabled without delay

   114      */

   115     virtual void EnableAudio( TBool aEnable, TBool aDelay = ETrue ) = 0;

   116 

   117     /**

   118      * Gets the state for radio audio.

   119      *

   120      * This returns the information if radio could be played when

   121      * other conditions are valid. This should be false only when

   122      * some other application has cause disabling of auto resume.

   123      *

   124      * @return ETrue if radio audio could be played,

   125      *         EFalse if radio audio couldn't be played

   126      */

   127     virtual TBool RadioAudioEnabled() const = 0;

   128 

   129     /**

   130      * Sets the audio overriding flag

   131      *

   132      * @param aOverride ETrue if other audio resources are tried to be overriden.

   133      */

   134     virtual void SetAudioOverride( TBool aOverride ) = 0;

   135 

   136     /**

   137      * Adds an observer wich will be notified of the radio state changes

   138      * If observer already exists, it is not added

   139      *

   140      * @param aObserver pointer of the observer instance.

   141      */

   142     virtual void AddObserverL( MRadioEngineObserver* aObserver ) = 0;

   143 

   144     /**

   145      * Removes a radio state change observer.

   146      */

   147     virtual void RemoveObserver( MRadioEngineObserver* aObserver ) = 0;

   148 

   149     /**

   150      * Sets audio mode ( Stereo/Mono )

   151      *

   152      * @param aAudioMode actual new radio mode

   153      */

   154     virtual void SetAudioMode( TInt aAudioMode ) = 0;

   155 

   156     /**

   157      * Compares if frequency is within limits range.

   158      *

   159      * @param aFrequency The frequency that is checked.

   160      *                   If omitted, current frequency is checked.

   161      * @return ETrue, if frequency is within radio range.

   162      */

   163     virtual TBool IsFrequencyValid( TUint32 aFrequency = 0 ) const = 0;

   164 

   165     /**

   166      * Tunes to frequency

   167      * If radio is not initialized by InitRadioL, frequency is just

   168      * set to settings.

   169      *

   170      * @param aFrequency frequency to tune to

   171      * @param aReason reason for the frequency setting

   172      */

   173     virtual void SetFrequency( TUint32 aFrequency,

   174             RadioEngine::TRadioFrequencyEventReason aReason = RadioEngine::ERadioFrequencyEventReasonUnknown ) = 0;

   175 

   176     /**

   177      * Test function to try to make the tuning as fast as possible.

   178      * Use with care since this will skip a lot of checks done by the SetFrequency() function

   179      */

   180     virtual void SetFrequencyFast( TUint32 aFrequency,

   181             RadioEngine::TRadioFrequencyEventReason aReason = RadioEngine::ERadioFrequencyEventReasonUnknown ) = 0;

   182 

   183     /**

   184      * Steps to next frequency according to direction

   185      *

   186      * @param aDirection The direciton to step to

   187      */

   188     virtual void StepToFrequency( RadioEngine::TRadioTuneDirection aDirection ) = 0;

   189 

   190     /**

   191      * Performs seeking operation.

   192      *

   193      * @param aDirection direction of seeking operation.

   194      */

   195     virtual void Seek( RadioEngine::TRadioTuneDirection aDirection ) = 0;

   196 

   197     /**

   198      * Cancels an ongoing request to seek up/down.

   199      */

   200     virtual void CancelSeek() = 0;

   201 

   202     /**

   203      * Is the radio seeking up/down, or at all.

   204      *

   205      * @return Seeking state.

   206      */

   207     virtual RadioEngine::TRadioSeeking Seeking() const = 0;

   208 

   209     /**

   210      * Starts scanning all available stations from the minimum frequency

   211      *

   212      * Calling this method also cancels any existing scan or seek operations.

   213      *

   214      * @param   aObserver       Observer to be notified of the progress of the scan.

   215      *                          If a scan is currently in progress or the radio is not on, then

   216      *                          the new scan is not performed at all and an error is passed on completion event.

   217      *

   218      */

   219     virtual void StartScan( MRadioScanObserver& aObserver ) = 0;

   220 

   221     /**

   222      * Stops any scans currently in progress and notifies the observer

   223      *

   224      * @param aError The error code for completing the scanning.

   225      */

   226     virtual void StopScan( TInt aError = KErrCancel ) = 0;

   227 

   228     /**

   229      * Changes volume by one level.

   230      *

   231      * @param aDirection Direction of the volume change.

   232      */

   233     virtual void AdjustVolume( RadioEngine::TRadioVolumeSetDirection aDirection ) = 0;

   234 

   235     /**

   236      * Sets volume level

   237      *

   238      * @param aVolume new volume level.

   239      */

   240     virtual void SetVolume( TInt aVolume ) = 0;

   241 

   242     /**

   243      * Sets volume to be muted.

   244      *

   245      * @param aMute mute status.

   246      */

   247     virtual void SetVolumeMuted( TBool aMute ) = 0;

   248 

   249     /**

   250      * Retrieves current antenna state.

   251      *

   252      * @return ETrue if antenna is attached, EFalse otherwise.

   253      */

   254     virtual TBool IsAntennaAttached() = 0;

   255 

   256     /**

   257      * Retrieves current state of fm transmitter.

   258      *

   259      * @return ETrue if fm transmitter is active, EFalse otherwise.

   260      */

   261     virtual TBool IsFmTransmitterActive() const = 0;

   262 

   263     /**

   264      * Changes the antenna state.

   265      * This should only be used when faking the antenna

   266      * state in emulator environment.

   267      * Thus this should work only in WINS.

   268      *

   269      * @param aAntennaAttached The new antenna state.

   270      */

   271     virtual void SetAntennaAttached( TBool aAntennaAttached ) = 0;

   272 

   273     /**

   274      * Returns the maximum volume level

   275      *

   276      * @return maximum volume level

   277      */

   278     virtual TInt MaxVolumeLevel() const = 0;

   279 

   280     /**

   281      * Has the frequency been set by RDS AF search or not.

   282      *

   283      * @return ETrue if frequency was set by RDS AF, otherwise EFalse

   284      */

   285     virtual TBool FrequencySetByRdsAf() const = 0;

   286 

   287     /**

   288      * Getter for RDS receiver

   289      *

   290      * @return Reference to CRadioRdsReceiver

   291      */

   292      virtual MRadioRdsReceiver& RdsReceiver() = 0;

   293 

   294     /**

   295      * Is routing between loudspeaker and headset possible

   296      *

   297      * @return ETrue, if routing is possible

   298      */

   299      virtual TBool IsAudioRoutingPossible() const = 0;

   300 

   301     /**

   302      * Checks if the radio playing parameters are OK

   303      *

   304      * @param aFrequency The frequency that is wanted to play.

   305      * @return ETrue if audio can be played, otherwise EFalse

   306      */

   307     virtual TBool OkToPlay( TUint32 aFrequency ) const = 0;

   308 

   309 protected:

   310 

   311     CRadioEngine( CRadioAudioRouter* aAudioRouter );

   312 

   313     };

   314 

   315 #endif // CRADIOENGINE_H_