/*

* 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 radio playback,

*                audio settings such as volume, balance, etc. In addition, this

*                class implements Custom Command API so clients can utilize it

*                with Audio Enhancement features provides by MultiMedia Framework (MMF).

*

*

*/

#ifndef C_RADIOPLAYERUTILITY_H

#define C_RADIOPLAYERUTILITY_H

#include <RadioUtility.h>

#include <MCustomInterface.h>

class RRadioSession;

/**  Player state */

enum TPlayerState

    {

	/**  Radio is idle (i.e. not playing) */

    ERadioPlayerIdle,

    /**  Radio is playing */

    ERadioPlayerPlaying

    };

/**

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

 *  complete notification from radio player utility. These functions are called once the

 *  asynchronous request completes successfully or with an error.

 *

 *  In addition, this class provides the interface for receiving events about radio playback.

 *

 *  @since S60 3.2

 */

class MRadioPlayerObserver

    {

public:

    /**

     * Radio state changed. This event is asynchronous and is received after a call to

	 * CRadioPlayerUtility::Play and CRadioPlayerUtility::Stop. This event is also generated when

	 * the radio is disrupted due to an error.

	 *

     * If the radio is disrupted due to an error, appropriate error code will be sent.

     * The following are the most common error codes: KErrDied when radio is pre-empted by another

     * application with higher priority, KErrHardwareNotAvailable when tuner is forced off

     * (e.g. when FM transmitter is turned on).

     *

     * @since S60 3.2

     * @param aState Radio player state

     * @param aError A standard system error code, only used when aState is ERadioPlayerIdle

     */

    virtual void MrpoStateChange( TPlayerState aState, TInt aError ) = 0;

    /**

     * Called when volume changes. This may be caused by other applications.

     *

     * @since S60 3.2

     * @param aVolume Current volume.

     */

    virtual void MrpoVolumeChange( TInt aVolume ) = 0;

    /**

     * Called when mute setting changes. This may be caused by other applications.

     *

     * @since S60 3.2

     * @param aMute ETrue indicates audio is muted.

     */

    virtual void MrpoMuteChange( TBool aMute ) = 0;

    /**

     * Called when balance setting changes. This may be caused by other applications.

     *

     * @since S60 3.2

     *        Left speaker volume percentage. This can be any value from zero to 100.

     *        Zero value means left speaker is muted.

     * @param aRightPercentage

     *        Right speaker volume percentage. This can be any value from zero to 100.

     *        Zero value means right speaker is muted.

     */

    virtual void MrpoBalanceChange( TInt aLeftPercentage, TInt aRightPercentage ) = 0;

    };

/**

 *  This class provides an interface to initiate and control playback of audio from the tuner.

 *

 *  @lib RadioUtility.lib

 *  @since S60 3.2

 */

class CRadioPlayerUtility : public CBase,

                            public MCustomInterface

    {

    friend class CRadioUtility::CBody;

public:

    /**

     * Retrieve the current state of the player.

     * If the radio is already playing, client should simply retrieve current settings such

     * as volume, etc.

     *

     * @since S60 3.2

     * @return Radio player state.

     */

    IMPORT_C TPlayerState PlayerState() const;

    /**

     * Close the radio player and free all memory allocated. Any ongoing playing activity will

     * be stopped if no other clients need it.

     *

     * @since S60 3.2

     */

	IMPORT_C void Close();

    /**

     * Asynchronous request to start playing the radio.

     *

     * User must be ready to receive callback method MrpoStateChange.

     * If radio plays successfully, the user will receive callback method MrpoStateChange with

     * ERadioPlayerPlaying and KErrNone. If a problem is encountered, user will receive

     * callback MrpoStateChange with ERadioPlayerIdle with an error code.

     *

     * @since S60 3.2

     * @see MRadioPlayerObserver::MrpoStateChange

     */

    IMPORT_C void Play();

    /**

     * Asynchronous request to stop the radio.

     *

     * This will stop radio for all client applications playing the radio. If the application

     * wishes to terminate without disrupting the radio playback (in case of multiple

     * active applications running), the application should terminate without issuing Stop.

     * User must be ready to receive callback method MrpoStateChange.

     *

     * @since S60 3.2

     * @see MRadioPlayerObserver::MrpoStateChange

     */

    IMPORT_C void Stop();

    /**

     * Get the maximum volume supported by the device. Volume range from 0 to max.

     * Setting volume to zero will mute the speakers.

     *

     * @since S60 3.2

     * @param aMaxVolume On return contains the maximum volume supported.

     * @return A standard system error code.

     */

    IMPORT_C TInt GetMaxVolume( TInt& aMaxVolume ) const;

    /**

     * Set the volume to the specified level. This can be any value from zero to max returned

     * by GetMaxVolume.

     *

     * @since S60 3.2

     * @param aVolume The volume level to set.

     * @return A standard system error code.

     */

    IMPORT_C TInt SetVolume( TInt aVolume );

    /**

     * Get the current volume.

     *

     * @since S60 3.2

     * @param aVolume On return contains the current volume.

     * @return A standard system error code.

     */

    IMPORT_C TInt GetVolume( TInt& aVolume ) const;

    /**

     * Set a volume ramp. Must be called before Play.

     * @param aRampInterval

     *        The time interval over which the volume should be increased from zero to

     *        the current volume setting.

     *

     * @since S60 3.2

     * @return A standard system error code.

     */

    IMPORT_C TInt SetVolumeRamp( const TTimeIntervalMicroSeconds& aRampInterval );

    /**

     * Mutes or unmutes radio playback.

     *

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

     * @since S60 3.2

     * @return A standard system error code.

     */

    IMPORT_C TInt Mute( TBool aMute );

    /**

     * Find out if the audio is muted or not.

     *

     * @since S60 3.2

     * @return ETrue if audio is muted.

     */

    IMPORT_C TBool IsMute();

    /**

     * Set the speaker balance for playing.

     *

     * @since S60 3.2

     * @param aLeftPercentage

     *        Left speaker volume percentage. This can be any value from zero to 100.

     *        Setting a zero value mutes the sound on left speaker.

     * @param aRightPercentage

     *        Right speaker volume percentage. This can be any value from zero to 100.

     *        Setting a zero value mutes the sound on right speaker.

     * @return A standard system error code.

     */

    IMPORT_C TInt SetBalance( TInt aLeftPercentage, TInt aRightPercentage );

    /**

     * Get the speaker balance set for playing.

     *

     * @since S60 3.2

     * @param aLeftPercentage

     *        On return contains left speaker volume perecentage. This can be any value

     *        from zero to 100. Zero value means left speaker is muted.

     * @param aRightPercentage

     *        On return contains right speaker volume perecentage. This can be any value

     *        from zero to 100. Zero value means right speaker is muted.

     * @return A standard system error code.

     */

    IMPORT_C TInt GetBalance( TInt& aLeftPercentage, TInt& aRightPercentage ) const;

    /**

     * Retrieves a custom interface to the device. (Used by Audio Enhancement)

     *

     * @since S60 3.2

     * @param aInterfaceId The interface UID, defined with the custom interface.

     * @return A pointer to the interface implementation, or NULL if the device does not

     * implement the interface requested. The return value must be cast to the correct

     * type by the user.

     */

    IMPORT_C TAny* CustomInterface( TUid aInterfaceId );

private:

    /**

     * Factory function to create a new instance of the radio player utility.

     *

     * @since S60 3.2

     * @param aRadioSession Reference to radio session

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

     * @return A new radio player utility object.

     */

    static CRadioPlayerUtility* NewL( RRadioSession& aRadioSession, MRadioPlayerObserver& aObserver );

    ~CRadioPlayerUtility();

    CRadioPlayerUtility();

    void ConstructL();

private: // data

    class CBody;

    /**

     * Radio player utility implementation body

     * Own.

     */

    CBody* iBody;

	};

#endif	// C_RADIOPLAYERUTILITY_H

// End of File