--- /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 <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
\ No newline at end of file