diff -r 000000000000 -r 71ca22bcf22a mmmw_plat/radio_utilities_api/inc/RadioPlayerUtility.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmmw_plat/radio_utilities_api/inc/RadioPlayerUtility.h Tue Feb 02 01:08:46 2010 +0200 @@ -0,0 +1,285 @@ +/* +* 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 +#include + +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 \ No newline at end of file