// Copyright (c) 2002-2009 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:

 //

 #ifndef __MDAAUDIOOUTPUTSTREAM_H

 #define __MDAAUDIOOUTPUTSTREAM_H

 #include <e32std.h>

 #include <mmf/common/mmfbase.h>

 #include <mmf/common/mmfstandardcustomcommands.h>

 #include <mda/common/base.h>      

 #include <mda/client/utility.h>

 #include <mmf/common/mmfaudio.h>

 #include <mmfclntutility.h>

 /**

 @publishedAll

 @released

 An interface class that notifies the client of the progress of audio output streaming.

 It must be implemented by users of the CMdaAudioOutputStream class.

 An object that implements this interface is passed to CMdaAudioOutputStream::NewL().

 */

 class MMdaAudioOutputStreamCallback 

 	{

 public:

 	/**

 	A callback function that is called when CMdaAudioOutputStream::Open() has completed, indicating that the

 	audio output stream is ready for use.

 	@param  aError

 	        An error value which indicates if open was completed successfully. KErrNone if succeeded.

 	*/

 	virtual void MaoscOpenComplete(TInt aError) = 0;

 	/**

 	A callback function that is called when a descriptor has been copied to the lower layers of MMF. 

 	It is also called when an error has occurred or when the client has stopped the stream playing before the descriptor 

 	has been fully copied (by calling CMdaAudioOutputStream::Stop()).

 	This function indicates to the client that it is safe to destroy the buffer passed to CMdaAudioOutputStream::WriteL(). 

 	It can also be used to make the next call to WriteL().

 	@param  aError

 	        KErrNone if the copy succeeded, otherwise one of the system error codes. KErrAbort indicates that 

 	        the client has stopped the stream playing before the descriptor has been copied.

 	@param  aBuffer

 	        A reference to the buffer that has been copied.

 	*/

 	virtual void MaoscBufferCopied(TInt aError, const TDesC8& aBuffer) = 0;

 	/**

 	A callback function that is called when playback terminates as a result of a CMdaAudioOutputStream::Stop().

 	If the end of the sound data has been reached, the function returns KErrUnderFlow. If playback terminates for any 

 	other reason, the function returns an appropriate error value.

 	@param  aError

 	        An error value which indicates play success or not. KErrNone if the close succeeded, otherwise one of the

 	        system error codes.

 	*/

 	virtual void MaoscPlayComplete(TInt aError) = 0;

 	};

 class CMMFMdaAudioOutputStream;

 /**

 @publishedAll

 @released

 The interface to an audio stream player passing raw audio data from specified buffers to the audio hardware.

 This class enables MMF clients to:

 Stream raw audio data to the audio hardware from specified buffers

 Specify the priority of the audio stream in relation to other clients that may request to use the same audio hardware

 Set the sample rate and the number of channels after successfully opening the stream. It is not possible to change these 

 values once  streaming has started.

 Change the volume and balance before or while the stream is open for writing. Volume and balance settings take effect immediately.

 The API supports callbacks from the server to notify the client:

 MaoscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the

 audio hardware as a result of a previous call to Open().

 MaoscBufferCopied() will be called each time audio data has been successfully copied to the lower layers of the

 MMF as a result of a previous WriteL().

 MaoscPlayComplete() will be called when the audio data stream has been closed as a result of a previous Stop().

 */

 class CMdaAudioOutputStream : public CBase,

 							  public MMMFClientUtility

 	{

 public:

 	/**

 	Allocates and constructs an audio stream player object.

 	@param  aCallBack

 	        A callback to notify the client when the sound device is open and ready to receive data, when 

 	        each descriptor has been copied and when the stream is closed. The caller must create a 

 	        callback class which implements this interface.

 	@param  aServer

 	        A pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided 

 	        for backward compatibility.

 	@return A pointer to new audio stream player.

 	*/

 	IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,

 												CMdaServer* aServer = NULL);

 	/**

 	Constructs and initialises a new instance of an audio streaming object.

 	The function leaves if the audio streaming object cannot be created.

 	@param  aCallBack

 	        A callback to notify the client when the sound device is open and ready to receive data, when each

 	        descriptor has been copied and when the stream is closed. The caller must create a callback class

 	        which implements this interface.

     @param  aPriority

             The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and 

             EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request.

     @param  aPref

             The Priority Preference - an additional audio policy parameter. The suggested default is 

             EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional 

             values may be supported by given phones and/or platforms, but should not be depended upon by 

             portable code.

 	@return A pointer to CMdaAudioOutputStream.

     Note: The Priority Value and Priority Preference are used primarily when deciding what to do when

     several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference, 

     the adaptation may consider other parameters such as the SecureId and Capabilities of the client process. 

     Whatever, the decision  as to what to do in such situations is up to the audio adaptation, and may

     vary between different phones. Portable applications are advised not to assume any specific behaviour. 

 	*/

 	IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,

 												TInt aPriority,

 												TInt aPref = EMdaPriorityPreferenceTimeAndQuality);

 	/**

     Destructor.

 	Frees all resources owned by the object prior to its destruction.

 	*/

 	~CMdaAudioOutputStream();

 	/**

 	Sets the sample rate and number of audio channels.

 	@param  aSampleRate

 	        The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.

 	@param  aChannels

 	        The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.

 	*/

 	virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);

 	/**

 	Opens an output audio stream package.

 	The MMdaAudioOutputStreamCallback::MaoscOpenComplete() callback function is called when the stream has been 

 	opened and is ready to receive audio data. If the open was unsuccessful, this is indicated by the aError 

 	parameter of the callback.

 	@param  aSettings

 	        A pointer to a TMdaPackage object.

 	*/

 	virtual void Open(TMdaPackage* aSettings);

 	/**

 	Returns the maximum volume level.

 	@return The maximum volume level supported by the sound device, as an integer.

 	*/

 	virtual TInt MaxVolume();

 	/**

 	Returns the current volume.

 	@return The current volume as an integer.

 	*/

 	virtual TInt Volume();

 	/**

 	Sets the audio volume.

 	Set the volume to zero for "sound off" or any other value between 1 and MaxVolume().

 	@param  aNewVolume

 	        A specified audio volume.

 	*/

 	virtual void SetVolume(const TInt aNewVolume);

 	/**

 	Sets the audio priority values.

 	This function cannot be used while the stream object is open. It is intended for use before an Open() 

 	is issued, or between a previous Stop() and a new Open().

 	@param  aPriority

 	        The Priority Value.

 	@param  aPref

 	        The Priority Preference.

     @see CMdaAudioOutputStream::NewL()

 	*/

 	virtual void SetPriority(TInt aPriority, TInt aPref);

 	/**

 	Writes (plays) streaming raw audio data.

 	This function is asynchronous. When aData has been received, the client is notified by a call to 

 	MMdaAudioOutputStreamCallback::MaoscBufferCopied(). The client can call WriteL() again before this notification 

 	takes place because the buffers are maintained in a client-side queue until they have been sent. An active object 

 	performs the notification, and copies the next item in the queue to the server.

 	MMdaAudioOutputStreamCallback::MaoscPlayComplete() is called when all descriptors have been sent.

 	@param  aData

 	        A reference to the stream data.

 	*/

 	virtual void WriteL(const TDesC8& aData);

 	/**

 	Stops writing data to a stream.

 	*/

 	virtual void Stop();

 	/**

 	Pause data rendering by audio hardware.

 	@return  An error code indicating if the operation was successful. KErrNone on success, 

 		KErrNotReady if not streaming

 		KErrNotSupported if trying to pause when resume is not supported by DevSound

 	*/

 	IMPORT_C TInt Pause();

 	/**

 	Resume data rendering by audio hardware.

 	@return  An error code indicating if the operation was successful. KErrNone on success, 

 		KErrNotReady if not paused. 

 		KErrNotSupported if trying to resume when resume is not supported by DevSound

 	*/

 	IMPORT_C TInt Resume();

 	/**

 	Returns the current position within the data stream.

 	@return The current position within the stream in microseconds.

 	*/

 	virtual const TTimeIntervalMicroSeconds& Position();

 	/**

 	Sets the audio balance.

 	@param  aBalance

 	        A specified balance volume. Default is KMMFBalanceCenter.

 	*/

 	IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);

 	/**

 	Returns the current balance as an integer.

 	@return The current balance value as integer.

 	*/

 	IMPORT_C TInt GetBalanceL() const;

 	/**

 	Returns the current number of bytes rendered by audio hardware.

 	@return The current current number of bytes rendered by audio hardware as an integer.

 	*/

 	IMPORT_C TInt GetBytes();

 	/**

     Sets the data type.  If the data type is not explicitly set it will assumed to be pcm16.

     If it is set then the hardware must support the data type being set otherwise the 

     function leaves with KErrNotSupported.

     @param	aAudioType The fourCC code used to specify the data type of the streamed audio

 	@leave KErrNotSupported

 	       Leaves with this for any unsuported data type.

 	*/

     IMPORT_C void SetDataTypeL(TFourCC aAudioType);

 	/**

 	Returns the current data type.

 	@return The ID of the data type.

 	*/

 	IMPORT_C TFourCC DataType() const;

 	/**

 	Registers the Event for Notification when resource is avaliable.

 	@param	aCallback

 	      	The audio outputstream observer interface..

 	@param 	aNotificationEventUid

 	 	The Event for which the client is registered.

 	@param 	aNotificationRegistrationData

 		Notification registration specific data.

 	@return An error code indicating if the registration was successful. KErrNone on success, 

 		otherwise another of the system-wide error codes.

 	*/

 	IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback& aCallback,TUid aNotificationEventUid,const TDesC8& aNotificationRegistrationData = KNullDesC8);

 	/**

 	Cancels the registered notification event.

 	@param  aNotificationEventUid

 		The Event to notify the client.

 	@return An error code indicating if the registration was successful. KErrNone on success, 

 		otherwise another of the system-wide error codes.

 	*/

 	IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);

     	/**

 	Waits for the client to resume the play even after the default timer expires.

 	@return An error code indicating if the registration was successful. KErrNone on success, 

 		otherwise another of the system-wide error codes.

 	*/

 	IMPORT_C TInt WillResumePlay();

 	/**

 	Retrieves a custom interface to the underlying device.

 	@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);

 	/**

 	When this method is called, AudioOutputStream goes into a different mode wherein it does not call 

 	MaoscPlayComplete() with KErrUnderflow when all the supplied data has been played. Instead client 

 	should signal the end of the play by calling RequestStop() or Stop() on AudioOutputStream.

 	If the client calls RequestStop(), AudioOutputStream waits until all the queued data has been played out

 	and then calls MaoscPlayComplete(). This behaviour is different from that of Stop(), which stops the play

 	immediately by discarding all the queued data.

 	Client should call this method on CMdaAudioOutputStream just after its construction and its 

 	effect remains through out its lifetime.

 	Note: This feature is supported only on a DevSound which ignores the underflow errors in the middle of

 	the play i.e which returns ETrue from QueryIgnoresUnderflow().

 	@return KErrNone on success, 

 			KErrNotSupported if the underlying DevSound does not ignore the underflow errors in the middle of the play

 	@see CMdaAudioOutputStream::RequestStop()

 	@see CMMFDevSound::QueryIgnoresUnderflow()

 	*/

 	IMPORT_C TInt KeepOpenAtEnd();

 	/**

 	This method signals the end of play when the AudioOutputStream is in KeepOpenAtEnd mode i.e when client

 	makes KeepOpenAtEnd call on it. When RequestStop is called, AudioOutputStream completes playing all

 	the data that is supplied to it and calls MaoscPlayComplete() with KErrUnderflow.

 	Note: Before calling this method, client must have already called KeepOpenAtEnd() successfully, Otherwise, this

 		  method returns KErrNotSupported. 

 		  It is recommended to use KeepOpenAtEnd and RequestStop calls to get a predictable behaviour during stopping.

 	@return KErrNone on success

 			KErrNotSupported when this method is called without calling KeepOpenAtEnd

 			KErrNotReady when this method is called before completing previous RequestStop or AudioOutputStream

 			is already in the stopped state

 	@see CMdaAudioOutputStream::KeepOpenAtEnd()

 	*/

 	IMPORT_C TInt RequestStop();

 private:

 	CMdaAudioOutputStream();

 private:

 	/**

 	This member is internal and not intended for use.

 	*/

 	CMMFMdaAudioOutputStream* iProperties;

 	};

 #endif