/*

* 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:  This class provides an interface for controlling the FM tuner

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

*                observer class is provided for receiving completion notification

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

*                events notifying changes in the tuner such as frequency change

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

*                control,etc.

*

*

*/

#ifndef C_RADIOFMTUNERUTILITY_H

#define C_RADIOFMTUNERUTILITY_H

#include <RadioUtility.h>

class RRadioSession;

/**

 *  FM tuner error definitions.

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

 *  be returned.

 */

typedef TInt TFmRadioTunerError;

const TFmRadioTunerError KFmRadioErrHardwareFaulty              = -12050;

const TFmRadioTunerError KFmRadioErrTuning                      = -12051;

const TFmRadioTunerError KFmRadioErrFrequencyOutOfBandRange     = -12052;

const TFmRadioTunerError KFmRadioErrFrequencyNotValid           = -12053;

const TFmRadioTunerError KFmRadioErrNotPermittedInCurrentState 	= -12054;

const TFmRadioTunerError KFmRadioErrDuplicateRequest            = -12055;

const TFmRadioTunerError KFmRadioErrAntennaNotConnected	        = -12056;

const TFmRadioTunerError KFmRadioErrFmTransmitterActive	        = -12057;

const TFmRadioTunerError KFmRadioErrOfflineMode                 = -12058;

/**  FM radio frequency range */

enum TFmRadioFrequencyRange

    {

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

    EFmRangeJapan			= 0x02		// Japanese FM frequency range

    };

/**

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

 *  device, as retrieved using the function GetCapabilities.

 *

 *  @since S60 3.2

 */

class TFmTunerCapabilities

    {

public:

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

    enum TFmTunerFeatures

        {

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

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

        ETunerAvailableInOfflineMode	  = 0x01,

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

        ETunerRdsSupport                  = 0x02,

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

		// more extensive RDS feature support.

        ETunerDualTunerSupport            = 0x04

        };

public:

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

    TUint32 iTunerBands;

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

    TUint32 iTunerFunctions;

    // Reserved for future

    TUint32 iAdditionalFunctions1;

    // Reserved for future

    TUint32 iAdditionalFunctions2;

    };

/**

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

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

 *  request completes successfully or with an error.

 *

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

 *

 *  @since S60 3.2

 */

class MRadioFmTunerObserver

    {

public:

    /**

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

     * a call to CRadioFmTunerUtility::RequestTunerControl.

     *

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

     *

     * If this function returns KFMRadioErrAntennaNotConnected, KFMRadioErrFmTransmitterActive,

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

     * MrfteoAntennaStatusChanged, MrfteoFmTransmitterStatusChanged, MrfteoOfflineModeStatusChanged.

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

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

     *

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

     * this function returns KErrAlreadyExists.

     *

     * @since S60 3.2

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

     */

    virtual void MrftoRequestTunerControlComplete( TInt aError ) = 0;

    /**

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

     * a call to CRadioFmTunerUtility::SetFrequencyRange.

     *

     * @since S60 3.2

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

     */

    virtual void MrftoSetFrequencyRangeComplete( TInt aError ) = 0;

    /**

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

	 * CRadioFmTunerUtility::SetFrequency.

     *

     * @since S60 3.2

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

     */

    virtual void MrftoSetFrequencyComplete( TInt aError ) = 0;

    /**

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

	 * CRadioFmTunerUtility::StationSeek.

     *

     * @since S60 3.2

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

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

     */

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

    /**

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

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

     *

     * @since S60 3.2

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

     */

    virtual void MrftoFmTransmitterStatusChange( TBool aActive ) = 0;

    /**

     * Called when antenna status changes.

     *

     * @since S60 3.2

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

     */

    virtual void MrftoAntennaStatusChange( TBool aAttached ) = 0;

    /**

     * Called when offline mode status changes.

     * @since S60 3.2

     *

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

     */

    virtual void MrftoOfflineModeStatusChange( TBool aOfflineMode ) = 0;

    /**

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

     *

     * @since S60 3.2

     * @param aNewRange New frequency range.

     */

    virtual void MrftoFrequencyRangeChange( TFmRadioFrequencyRange aNewRange ) = 0;

    /**

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

     * applications or RDS if AF/TA is enabled.

     *

     * @since S60 3.2

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

     */

    virtual void MrftoFrequencyChange( TInt aNewFrequency ) = 0;

    /**

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

     *

     * @since S60 3.2

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

     */

    virtual void MrftoForcedMonoChange( TBool aForcedMono ) = 0;

    /**

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

     * This may be caused by other applications.

     *

     * @since S60 3.2

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

     */

    virtual void MrftoSquelchChange( TBool aSquelch ) = 0;

	};

/**

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

 *  present on a device.

 *

 *  @lib RadioUtility.lib

 *  @since S60 3.2

 */

class CRadioFmTunerUtility : public CBase

    {

    friend class CRadioUtility::CBody;

public:

    /**

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

     * any other method calls in this API.

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

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

     * (such as SetFrequency) can be made.

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

     *

     * @since S60 3.2

     * @see MRadioFmTunerObserver::MrftoRequestTunerControlComplete

     */

    IMPORT_C void RequestTunerControl();

    /**

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

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

     * clients need it.

     *

     * @since S60 3.2

     */

	IMPORT_C void Close();

    /**

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

     *

     * @since S60 3.2

     * @param aCaps The capabilities object to fill

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

     */

    IMPORT_C TInt GetCapabilities( TFmTunerCapabilities& aCaps );

    /**

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

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

     *

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

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

     * tuner device.

     *

     * Tuner functions are disabled in offline mode by default.

     *

     * @since S60 3.2

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

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

     */

    IMPORT_C TInt EnableTunerInOfflineMode( TBool aEnable );

    /**

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

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

     * to EFmRangeEuroAmerica.

     *

     * @since S60 3.2

     * @param aRange Frequency range

     */

    IMPORT_C void SetFrequencyRange( TFmRadioFrequencyRange aRange );

    /**

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

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

     *

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

     *

     * @since S60 3.2

     */

    IMPORT_C void CancelSetFrequencyRange();

    /**

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

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

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

     *

     * @since S60 3.2

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

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

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

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

     */

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

    /**

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

     * ready to receive callback method MrftoTuneComplete.

     *

     * @since S60 3.2

     * @param aFrequency The frequency to tune to

     * @see MRadioFmTunerObserver::MrftoTuneComplete

     */

    IMPORT_C void SetFrequency( TInt aFrequency );

    /**

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

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

     *

     * Has not effect if no tune operation is ongoing.

     *

     * @since S60 3.2

     */

    IMPORT_C void CancelSetFrequency();

    /**

     * Get the currently tuned frequency.

     *

     * @since S60 3.2

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

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

     */

    IMPORT_C TInt GetFrequency( TInt& aFrequency ) const;

    /**

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

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

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

     *

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

     * in the callback method and frequency will not change.

     *

     * @since S60 3.2

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

     * @see MRadioFmTunerObserver::MrftoStationSeekComplete

     */

    IMPORT_C void StationSeek( TBool aUpwards );

    /**

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

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

     *

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

     *

     * @since S60 3.2

     */

    IMPORT_C void CancelStationSeek();

    /**

     * Get the signal strenth of the currently tuned frequency.

     *

     * @since S60 3.2

     * @param aSignalStrength On return contains the signal strength.

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

     */

    IMPORT_C TInt GetSignalStrength( TInt& aSignalStrength ) const;

    /**

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

     *

     * @since S60 3.2

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

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

     */

    IMPORT_C TInt GetMaxSignalStrength( TInt& aMaxSignalStrength ) const;

    /**

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

     *

     * @since S60 3.2

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

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

     */

    IMPORT_C TInt GetStereoMode( TBool& aStereo ) const;

    /**

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

     *

     * @since S60 3.2

     * @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 or FM tuner error (TFmRadioTunerError).

     */

    IMPORT_C TInt ForceMonoReception( TBool aForcedMono );

    /**

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

     *

     * @since S60 3.2

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

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

     */

    IMPORT_C TInt GetForcedMonoReception( TBool& aForcedMono ) const;

    /**

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

     * Squelching is enabled by default.

     *

     * @since S60 3.2

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

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

     */

    IMPORT_C TInt SetSquelch( TBool aSquelch );

    /**

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

     *

     * @since S60 3.2

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

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

     */

    IMPORT_C TInt GetSquelch( TBool& aSquelch ) const;

private:

    /**

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

     *

     * @since S60 3.2

     * @param aRadioSession Reference to radio session

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

     * @return A new FM tuner utility object.

     */

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

    virtual ~CRadioFmTunerUtility();

    CRadioFmTunerUtility();

    void ConstructL();

private: // data

    class CBody;

    /**

     * FM tuner utility implementation body

     * Own.

     */

    CBody* iBody;

    };

#endif // C_RADIOFMTUNERUTILITY_H