/*

* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Header file for Tuner component.

*

*/

#ifndef TUNER_H

#define TUNER_H

#include <e32base.h>

#include <MCustomCommand.h>

#include <mmf/common/mmfbase.h>

#include <mmf/common/mmfutilities.h>

#include <mmf/common/mmfcontrollerframework.h>

#include <mmf/common/mmfstandardcustomcommands.h>

#include <mmf/common/mmfaudio.h>

#include <Mda/Common/audio.h>

class RRadioSession;

/**

@file

@publishedAll

@prototype

*/

/**

The Tuner Capabilities structure defines the capabilities of the tuner

on the device, as retrieved using the function GetCapabilities.

*/

class TTunerCapabilities

{

public:

    inline TTunerCapabilities();

    inline TTunerCapabilities(TUint32 aTunerBands, TUint32 aAdditionalFunctions);

public:

    /**

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

    supported bands set

    */

    TUint32 iTunerBands;

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

    enum TTunerFunctions

    {

        /** Recording of Tuner Audio is possible */

        ETunerFunctionRecording                 = 0x01,

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

        ETunerFunctionSimultaneousPlayAndRecord = 0x02,

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

        ETunerFunctionRequiresAntenna           = 0x04,

        /** CMMRdsTunerUtility supported */

        ETunerFunctionRds                       = 0x08,

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

        ETunerFunctionAvailableInFlightMode     = 0x10

    };

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

    TUint32 iAdditionalFunctions;

};

/**

Class representing a frequency.

*/

class TFrequency

{

public:

    inline TFrequency();

    explicit inline TFrequency(TInt aFrequency);

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

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

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

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

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

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

public:

    /**

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

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

    */

    TInt iFrequency;

};

class MMMTunerObserver;

class MMMTunerChangeObserver;

class MMMTunerStereoObserver;

class MMMSignalStrengthObserver;

class MMMTunerAudioPlayerObserver;

class MMMTunerAudioRecorderObserver;

class CMMTunerAudioPlayerUtility;

class CMMTunerAudioRecorderUtility;

class CMMTunerScannerUtility;

class CMMRdsTunerUtility;

/**

The MMF Tuner API is present to allow clients to control

the tuner hardware present on a device.

*/

class CMMTunerUtility : public CBase

{

    friend class CMMTunerAudioPlayerUtility;

    friend class CMMTunerAudioRecorderUtility;

    friend class CMMTunerScannerUtility;

    friend class CMMRdsTunerUtility;

public:

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

    enum TTunerBand

    {

        ETunerNoBand            = 0x00,

        /** Long Wave - uses frequencies */

        ETunerBandLw            = 0x01,

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

        ETunerBandAm            = 0x02,

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

        ETunerBandFm            = 0x04,

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

        ETunerBandJapaneseFm    = 0x08,

        /** Digital Audio Broadcasting - uses channels */

        ETunerBandDab           = 0x10,

        /** Digital Video Broadcasting */

        ETunerBandDvb           = 0x20

    };

    /**

    Search direction enumeration

    */

    enum TSearchDirection

    {

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

        ESearchDirectionUp = 1,

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

        ESearchDirectionDown

    };

    /**

    The Tuner Access Priority enables clients to correctly identify their needs

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

    capability to use priorities greater than ETunerAccessPriorityNormal.

    */

    enum TTunerAccessPriority

    {

        /** Radio accessible when device is idle */

        ETunerAccessPriorityBackground      = -100,

        /** Ordinary application priority */

        ETunerAccessPriorityNormal          = 0,

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

        ETunerAccessPriorityAlarm           = 75,

        /** System use only */

        ETunerAccessPrioritySystem          = 100

    };

    /**

    Bitmasks to indicate what state the tuner is in.

    */

    enum TTunerState

    {

        /**

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

        not set, none of the others should be set.

        */

        ETunerStateActive       = 0x01,

        /** The tuner is playing sound. */

        ETunerStatePlaying      = 0x02,

        /** The tuner is currently recording. */

        ETunerStateRecording    = 0x04,

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

        ETunerStateRetuning     = 0x08,

    };

public:

    /**

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

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

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

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

    ready for use on return from this function.

    @param aObserver The observer object for receiving async completion callbacks

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

            device to use.

    @param aAccessPriority Tuner access priority value

    @leave KErrNoMemory Out of memory

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

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

    */

    IMPORT_C static CMMTunerUtility* NewL(MMMTunerObserver& aObserver,

                                          TTunerBand aBand,

                                          TInt aTunerIndex,

                                          CMMTunerUtility::TTunerAccessPriority aAccessPriority = ETunerAccessPriorityNormal);

    IMPORT_C virtual ~CMMTunerUtility();

    /**

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

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

    tuner.

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

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

    @param aAccessPriority The new priority to use.

    @capability MultimediaDD

    @return A standard system error code.

    */

    IMPORT_C TInt SetPriority(TTunerAccessPriority aAccessPriority);

    /**

    Get the current tuner access priority of this client.

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

    @return A standard system error code.

    */

    IMPORT_C TInt GetPriority(TTunerAccessPriority& aAccessPriority) const;

    /**

    Get the current state of the tuner.

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

           TTunerState.

    @return A standard system error code.

    */

    IMPORT_C TInt GetState(TUint32& aState) const;

    /**

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

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

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

    imply that the tuner cannot be used.

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

           if an external antenna is attached.

    @return A standard system error code.

    */

    IMPORT_C TInt IsAntennaAttached(TBool& aAttached);

    /**

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

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

    mode or not.

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

            the device is in flight mode.

    @return A standard system error code.

    */

    IMPORT_C TInt GetFlightMode(TBool& aFlightMode) const;

    /**

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

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

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

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

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

    KErrAccessDenied.

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

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

    will be a callback to MToTunerError with error value KErrAccessDenied.

    @param aFrequency The frequency to tune to

    @param aBand The band to which aFrequency belongs

    */

    IMPORT_C void Tune(TFrequency aFrequency);

    /**

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

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

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

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

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

    with error value KErrAccessDenied.

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

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

    will be a callback to MToTunerError with error value KErrAccessDenied.

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

    @param aBand The band

    @param aSearchDirect The direction to search in

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

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

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

           in a callback to MToTuneComplete with error KErrNotFound.

    */

    IMPORT_C void StationSeek(TSearchDirection aSearchDirection);

    /**

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

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

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

    */

    IMPORT_C void CancelRetune();

    /**

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

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

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

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

    will occur.

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

    notifiaction when control could be granted can be made using

    NotifyTunerControl.

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

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

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

            control was denied KErrAccessDenied.

    */

    IMPORT_C TInt RequestTunerControl();

    /**

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

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

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

    will occur in this event.

    */

    IMPORT_C TInt NotifyTunerControl();

    /**

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

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

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

    of the tuner.

    */

    IMPORT_C void ReleaseTunerControl();

    /**

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

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

    no other clients need it.

    */

    IMPORT_C void Close();

    /**

    Retrieve the current frequency that the tuner is tuned to

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

    -1 if channels are in use

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

    @return A standard system error code

    */

    IMPORT_C TInt GetFrequency(TFrequency& aFrequency) const;

    /**

    Retrieve the signal strenth of the currently tuned signal

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

    @return A standard system error code

    */

    IMPORT_C TInt GetSignalStrength(TInt& aSignalStrength) const;

    /**

    Get the maximum possible signal strength of a tuned signal.

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

            written to.

    @return A standard system error code

    */

    IMPORT_C TInt GetMaxSignalStrength(TInt& aMaxSignalStrength) const;

    /**

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

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

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

    display of signal strength to be maintained fairly accurately.

    The first signal strength notification will be sent immediately after this

    request.

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

            changes.

    @return A standard system error code

    */

    IMPORT_C TInt NotifySignalStrength(MMMSignalStrengthObserver& aObserver);

    /**

    Cancel an outstanding NotifySignalStrength request.

    */

    IMPORT_C void CancelNotifySignalStrength();

    /**

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

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

           currently being received.

    */

    IMPORT_C TInt IsStereoSignal(TBool& aStereo);

    /**

    Request notifications when stereo reception is lost/restored.

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

           or restored. The first notification will occur immediately.

    @return A standard system error code

    */

    IMPORT_C TInt NotifyStereoChange(MMMTunerStereoObserver& aObserver);

    /**

    Cancels a stereo change notification request.

    */

    IMPORT_C void CancelNotifyStereoChange();

    /**

    Indicates whether the reception should be forced into monophonic mode.

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

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

           possible.

    @return A standard system error code.

    */

    IMPORT_C TInt ForceMonoReception(TBool aMono);

    /**

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

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

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

           available.

    @return A standard system error code.

    */

    IMPORT_C TInt GetForcedMonoReception(TBool& aMono) const;

    /**

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

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

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

    */

    IMPORT_C TInt SetSquelch(TBool aEnabled);

    /**

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

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

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

    */

    IMPORT_C TInt GetSquelch(TBool& aEnabled) const;

    /**

    Get the capabilities of the tuner on the device

    @param aCaps The capabilities object to fill

    @return A standard system error code

    */

    IMPORT_C TInt GetCapabilities(TTunerCapabilities& aCaps) const;

    /**

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

    This function should be used to enquire the frequency range

    of the bands that GetCapabilities reports as supported.

    @param aBand The band to query

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

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

    @return A standard system error code

    */

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

    /**

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

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

    @param aObserver The object wishing to receive tuning change events

    @return A standard system error code

    */

    IMPORT_C TInt NotifyChange(MMMTunerChangeObserver& aObserver);

    /**

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

    */

    IMPORT_C void CancelNotifyChange();

    /**

    Send a synchronous custom command to the tuner.

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

        on the interface defined by the first IPC argument

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

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

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

        argument properly will result in the command completing with

        KErrNotSupported at best, but possibly  the client being panicked.

    @return A standard system error code

    */

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

    /**

    Send an asynchronous custom command to the tuner.

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

        on the interface defined by the first IPC argument

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

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

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

        argument properly will result in the command completing with

        KErrNotSupported at best, but possibly  the client being panicked.

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

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

        dependent on the interface.

    */

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

    /**

    Get the Tuner Player Utility

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

    @return A standard system error code.

    */

    IMPORT_C CMMTunerAudioPlayerUtility* TunerPlayerUtilityL(MMMTunerAudioPlayerObserver& aObserver) ;

    /**

    Get the Tuner Recorder Utility

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

    @return A standard system error code.