williamr@2: // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #ifndef __MDAAUDIOOUTPUTSTREAM_H
williamr@2: #define __MDAAUDIOOUTPUTSTREAM_H
williamr@2: 
williamr@2: 
williamr@2: #include <e32std.h>
williamr@2: #include <mmf/common/mmfbase.h>
williamr@2: #include <mmf/common/mmfstandardcustomcommands.h>
williamr@2: #include <mda/common/base.h>      
williamr@2: #include <mda/client/utility.h>
williamr@2: #include <mmf/common/mmfaudio.h>
williamr@2: #include <mmfclntutility.h>
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: An interface class that notifies the client of the progress of audio output streaming.
williamr@2: 
williamr@2: It must be implemented by users of the CMdaAudioOutputStream class.
williamr@2: 
williamr@2: An object that implements this interface is passed to CMdaAudioOutputStream::NewL().
williamr@2: */
williamr@2: class MMdaAudioOutputStreamCallback 
williamr@2: 	{
williamr@2: public:
williamr@2: 
williamr@2: 	/**
williamr@2: 	A callback function that is called when CMdaAudioOutputStream::Open() has completed, indicating that the
williamr@2: 	audio output stream is ready for use.
williamr@2: 
williamr@2: 	@param  aError
williamr@2: 	        An error value which indicates if open was completed successfully. KErrNone if succeeded.
williamr@2: 	*/
williamr@2: 	virtual void MaoscOpenComplete(TInt aError) = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	A callback function that is called when a descriptor has been copied to the lower layers of MMF. 
williamr@2: 
williamr@2: 	It is also called when an error has occurred or when the client has stopped the stream playing before the descriptor 
williamr@2: 	has been fully copied (by calling CMdaAudioOutputStream::Stop()).
williamr@2: 
williamr@2: 	This function indicates to the client that it is safe to destroy the buffer passed to CMdaAudioOutputStream::WriteL(). 
williamr@2: 	It can also be used to make the next call to WriteL().
williamr@2: 
williamr@2: 	@param  aError
williamr@2: 	        KErrNone if the copy succeeded, otherwise one of the system error codes. KErrAbort indicates that 
williamr@2: 	        the client has stopped the stream playing before the descriptor has been copied.
williamr@2: 	@param  aBuffer
williamr@2: 	        A reference to the buffer that has been copied.
williamr@2: 	*/
williamr@2: 	virtual void MaoscBufferCopied(TInt aError, const TDesC8& aBuffer) = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	A callback function that is called when playback terminates as a result of a CMdaAudioOutputStream::Stop().
williamr@2: 
williamr@2: 	If the end of the sound data has been reached, the function returns KErrUnderFlow. If playback terminates for any 
williamr@2: 	other reason, the function returns an appropriate error value.
williamr@2: 
williamr@2: 	@param  aError
williamr@2: 	        An error value which indicates play success or not. KErrNone if the close succeeded, otherwise one of the
williamr@2: 	        system error codes.
williamr@2: 	*/
williamr@2: 	virtual void MaoscPlayComplete(TInt aError) = 0;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class CMMFMdaAudioOutputStream;
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: The interface to an audio stream player passing raw audio data from specified buffers to the audio hardware.
williamr@2: 
williamr@2: This class enables MMF clients to:
williamr@2: 
williamr@2: Stream raw audio data to the audio hardware from specified buffers
williamr@2: 
williamr@2: Specify the priority of the audio stream in relation to other clients that may request to use the same audio hardware
williamr@2: 
williamr@2: Set the sample rate and the number of channels after successfully opening the stream. It is not possible to change these 
williamr@2: values once  streaming has started.
williamr@2: 
williamr@2: Change the volume and balance before or while the stream is open for writing. Volume and balance settings take effect immediately.
williamr@2: 
williamr@2: The API supports callbacks from the server to notify the client:
williamr@2: 
williamr@2: MaoscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the
williamr@2: audio hardware as a result of a previous call to Open().
williamr@2: 
williamr@2: MaoscBufferCopied() will be called each time audio data has been successfully copied to the lower layers of the
williamr@2: MMF as a result of a previous WriteL().
williamr@2: 
williamr@2: MaoscPlayComplete() will be called when the audio data stream has been closed as a result of a previous Stop().
williamr@2: */
williamr@2: class CMdaAudioOutputStream : public CBase,
williamr@2: 							  public MMMFClientUtility
williamr@2: 	{
williamr@2: public:
williamr@2: 
williamr@2: 	/**
williamr@2: 	Allocates and constructs an audio stream player object.
williamr@2: 
williamr@2: 	@param  aCallBack
williamr@2: 	        A callback to notify the client when the sound device is open and ready to receive data, when 
williamr@2: 	        each descriptor has been copied and when the stream is closed. The caller must create a 
williamr@2: 	        callback class which implements this interface.
williamr@2: 	@param  aServer
williamr@2: 	        A pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided 
williamr@2: 	        for backward compatibility.
williamr@2: 
williamr@2: 	@return A pointer to new audio stream player.
williamr@2: 	*/
williamr@2: 	IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,
williamr@2: 												CMdaServer* aServer = NULL);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Constructs and initialises a new instance of an audio streaming object.
williamr@2: 
williamr@2: 	The function leaves if the audio streaming object cannot be created.
williamr@2: 
williamr@2: 	@param  aCallBack
williamr@2: 	        A callback to notify the client when the sound device is open and ready to receive data, when each
williamr@2: 	        descriptor has been copied and when the stream is closed. The caller must create a callback class
williamr@2: 	        which implements this interface.
williamr@2: 	@param  aPriority
williamr@2: 	        This client's relative priority. This is a value between EMdaPriorityMin and EMdaPriorityMax and represents
williamr@2: 	        a relative priority. A higher value indicates a more important request.
williamr@2: 	@param  aPref
williamr@2: 	        The required behaviour if a higher priority client takes over the sound output device.
williamr@2: 
williamr@2: 	@return A pointer to CMdaAudioOutputStream.
williamr@2: 
williamr@2: 	@capability MultimediaDD
williamr@2: 	            A process requesting or using this method that has MultimediaDD capability will
williamr@2: 				always have precedence over a process that does not have MultimediaDD.
williamr@2: 	*/
williamr@2: 	IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,
williamr@2: 												TInt aPriority,
williamr@2: 												TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality);
williamr@2: 
williamr@2: 
williamr@2: 	/**
williamr@2:     Destructor.
williamr@2: 
williamr@2: 	Frees all resources owned by the object prior to its destruction.
williamr@2: 	*/
williamr@2: 	~CMdaAudioOutputStream();
williamr@2: 
williamr@2: 	/**
williamr@2: 	Sets the sample rate and number of audio channels.
williamr@2: 
williamr@2: 	@param  aSampleRate
williamr@2: 	        The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
williamr@2: 	@param  aChannels
williamr@2: 	        The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
williamr@2: 	
williamr@2: 	*/
williamr@2: 	virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Opens an output audio stream package.
williamr@2: 
williamr@2: 	The MMdaAudioOutputStreamCallback::MaoscOpenComplete() callback function is called when the stream has been 
williamr@2: 	opened and is ready to receive audio data. If the open was unsuccessful, this is indicated by the aError 
williamr@2: 	parameter of the callback.
williamr@2: 
williamr@2: 
williamr@2: 	@param  aSettings
williamr@2: 	        A pointer to a TMdaPackage object.
williamr@2: 	
williamr@2: 	*/
williamr@2: 	virtual void Open(TMdaPackage* aSettings);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Returns the maximum volume level.
williamr@2: 
williamr@2: 	@return The maximum volume level supported by the sound device, as an integer.
williamr@2: 	*/
williamr@2: 	virtual TInt MaxVolume();
williamr@2: 
williamr@2: 	/**
williamr@2: 	Returns the current volume.
williamr@2: 
williamr@2: 	@return The current volume as an integer.
williamr@2: 	*/
williamr@2: 	virtual TInt Volume();
williamr@2: 
williamr@2: 	/**
williamr@2: 	Sets the audio volume.
williamr@2: 
williamr@2: 	Set the volume to zero for "sound off" or any other value between 1 and MaxVolume().
williamr@2: 
williamr@2: 	@param  aNewVolume
williamr@2: 	        A specified audio volume.
williamr@2: 
williamr@2: 	*/
williamr@2: 	virtual void SetVolume(const TInt aNewVolume);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Sets the audio priority values.
williamr@2: 
williamr@2: 	This function cannot be used while the stream object is open. It is intended for use before an Open() 
williamr@2: 	is issued, or between a previous Stop() and a new Open().
williamr@2: 
williamr@2: 	@param  aPriority
williamr@2: 	        The priority level to apply, EMdaPriorityMin allows the client can be interrupted by any other client,
williamr@2: 	        EMdaPriorityNormal allows the client is only interrupted by clients with a higher priority or
williamr@2: 			EMdaPriorityMax allows the client cannot be interrupted by other clients.
williamr@2: 	@param  aPref
williamr@2: 	        A set of priority values that define the behaviour to be adopted by a client using a sound device if a 
williamr@2: 	        higher priority client takes over that device.
williamr@2: 
williamr@2: 
williamr@2: 	@capability MultimediaDD
williamr@2: 	            A process requesting or using this method that has MultimediaDD capability will
williamr@2: 				always have precedence over a process that does not have MultimediaDD.
williamr@2: 	*/
williamr@2: 	virtual void SetPriority(TInt aPriority, TMdaPriorityPreference aPref);
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Writes (plays) streaming raw audio data.
williamr@2: 
williamr@2: 	This function is asynchronous. When aData has been received, the client is notified by a call to 
williamr@2: 	MMdaAudioOutputStreamCallback::MaoscBufferCopied(). The client can call WriteL() again before this notification 
williamr@2: 	takes place because the buffers are maintained in a client-side queue until they have been sent. An active object 
williamr@2: 	performs the notification, and copies the next item in the queue to the server.
williamr@2: 	MMdaAudioOutputStreamCallback::MaoscPlayComplete() is called when all descriptors have been sent.
williamr@2: 
williamr@2: 	@param  aData
williamr@2: 	        A reference to the stream data.
williamr@2: 
williamr@2: 	*/
williamr@2: 	virtual void WriteL(const TDesC8& aData);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Stops writing data to a stream.
williamr@2: 
williamr@2: 	*/
williamr@2: 	virtual void Stop();
williamr@2: 
williamr@2: 	/**
williamr@2: 	Pause data rendering by audio hardware.
williamr@2: 	@return  An error code indicating if the operation was successful. KErrNone on success, 
williamr@2: 		KErrNotReady if not streaming
williamr@2: 		KErrNotSupported if trying to pause when resume is not supported by DevSound
williamr@2: 	*/
williamr@2: 
williamr@2: 	IMPORT_C TInt Pause();
williamr@2: 
williamr@2: 
williamr@2: 	/**
williamr@2: 	Resume data rendering by audio hardware.
williamr@2: 	@return  An error code indicating if the operation was successful. KErrNone on success, 
williamr@2: 		KErrNotReady if not paused. 
williamr@2: 		KErrNotSupported if trying to resume when resume is not supported by DevSound
williamr@2: 	*/
williamr@2: 	IMPORT_C TInt Resume();
williamr@2: 
williamr@2: 
williamr@2: 	/**
williamr@2: 	Returns the current position within the data stream.
williamr@2: 
williamr@2: 	@return The current position within the stream in microseconds.
williamr@2: 	*/
williamr@2: 	virtual const TTimeIntervalMicroSeconds& Position();
williamr@2: 
williamr@2: 	/**
williamr@2: 	Sets the audio balance.
williamr@2: 
williamr@2: 	@param  aBalance
williamr@2: 	        A specified balance volume. Default is KMMFBalanceCenter.
williamr@2: 
williamr@2: 	*/
williamr@2: 	IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Returns the current balance as an integer.
williamr@2: 
williamr@2: 	@return The current balance value as integer.
williamr@2: 	*/
williamr@2: 	IMPORT_C TInt GetBalanceL() const;
williamr@2: 
williamr@2: 	/**
williamr@2: 	Returns the current number of bytes rendered by audio hardware.
williamr@2: 
williamr@2: 	@return The current current number of bytes rendered by audio hardware as an integer.
williamr@2: 	*/
williamr@2: 	IMPORT_C TInt GetBytes();
williamr@2: 
williamr@2: 	/**
williamr@2:     Sets the data type.  If the data type is not explicitly set it will assumed to be pcm16.
williamr@2:     If it is set then the hardware must support the data type being set otherwise the 
williamr@2:     function leaves with KErrNotSupported.
williamr@2:     
williamr@2:     @param	aAudioType The fourCC code used to specify the data type of the streamed audio
williamr@2: 
williamr@2: 	@leave KErrNotSupported
williamr@2: 	       Leaves with this for any unsuported data type.
williamr@2: 	*/
williamr@2:     IMPORT_C void SetDataTypeL(TFourCC aAudioType);
williamr@2: 
williamr@2: 	/**
williamr@2: 	Returns the current data type.
williamr@2: 
williamr@2: 	@return The ID of the data type.
williamr@2: 	*/
williamr@2: 	IMPORT_C TFourCC DataType() const;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Registers the Event for Notification when resource is avaliable.
williamr@2: 	@param	aCallback
williamr@2: 	      	The audio outputstream observer interface..
williamr@2: 	@param 	aNotificationEventUid
williamr@2: 	 	The Event for which the client is registered.
williamr@2: 	@param 	aNotificationRegistrationData
williamr@2: 		Notification registration specific data.
williamr@2: 	@return An error code indicating if the registration was successful. KErrNone on success, 
williamr@2: 		otherwise another of the system-wide error codes.
williamr@2: 	*/
williamr@2: 	IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback& aCallback,TUid aNotificationEventUid,const TDesC8& aNotificationRegistrationData = KNullDesC8);
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Cancels the registered notification event.
williamr@2: 	@param  aNotificationEventUid
williamr@2: 		The Event to notify the client.
williamr@2: 		
williamr@2: 	@return An error code indicating if the registration was successful. KErrNone on success, 
williamr@2: 		otherwise another of the system-wide error codes.
williamr@2: 	*/
williamr@2: 	IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);
williamr@2:     
williamr@2:     	/**
williamr@2: 	Waits for the client to resume the play even after the default timer expires.
williamr@2: 	@return An error code indicating if the registration was successful. KErrNone on success, 
williamr@2: 		otherwise another of the system-wide error codes.
williamr@2: 	*/
williamr@2: 	IMPORT_C TInt WillResumePlay();
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Retrieves a custom interface to the underlying device.
williamr@2: 
williamr@2: 	@param  aInterfaceId
williamr@2: 	        The interface UID, defined with the custom interface.
williamr@2: 	
williamr@2: 	@return A pointer to the interface implementation, or NULL if the device does not
williamr@2: 	        implement the interface requested. The return value must be cast to the
williamr@2: 	        correct type by the user.
williamr@2: 	*/
williamr@2: 	IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
williamr@2: 	
williamr@2: 	/**
williamr@2: 	When this method is called, AudioOutputStream goes into a different mode wherein it does not call 
williamr@2: 	MaoscPlayComplete() with KErrUnderflow when all the supplied data has been played. Instead client 
williamr@2: 	should signal the end of the play by calling RequestStop() or Stop() on AudioOutputStream.
williamr@2: 	If the client calls RequestStop(), AudioOutputStream waits until all the queued data has been played out
williamr@2: 	and then calls MaoscPlayComplete(). This behaviour is different from that of Stop(), which stops the play
williamr@2: 	immediately by discarding all the queued data.
williamr@2: 	
williamr@2: 	Client should call this method on CMdaAudioOutputStream just after its construction and its 
williamr@2: 	effect remains through out its lifetime.
williamr@2: 	
williamr@2: 	Note: This feature is supported only on a DevSound which ignores the underflow errors in the middle of
williamr@2: 	the play i.e which returns ETrue from QueryIgnoresUnderflow().
williamr@2: 	
williamr@2: 	@return KErrNone on success, 
williamr@2: 			KErrNotSupported if the underlying DevSound does not ignore the underflow errors in the middle of the play
williamr@2: 				
williamr@2: 	@see CMdaAudioOutputStream::RequestStop()
williamr@2: 	@see CMMFDevSound::QueryIgnoresUnderflow()
williamr@2: 	*/
williamr@2: 	IMPORT_C TInt KeepOpenAtEnd();
williamr@2: 	
williamr@2: 	/**
williamr@2: 	This method signals the end of play when the AudioOutputStream is in KeepOpenAtEnd mode i.e when client
williamr@2: 	makes KeepOpenAtEnd call on it. When RequestStop is called, AudioOutputStream completes playing all
williamr@2: 	the data that is supplied to it and calls MaoscPlayComplete() with KErrUnderflow.
williamr@2: 	
williamr@2: 	Note: Before calling this method, client must have already called KeepOpenAtEnd() successfully, Otherwise, this
williamr@2: 		  method returns KErrNotSupported. 
williamr@2: 		  It is recommended to use KeepOpenAtEnd and RequestStop calls to get a predictable behaviour during stopping.
williamr@2: 	
williamr@2: 	@return KErrNone on success
williamr@2: 			KErrNotSupported when this method is called without calling KeepOpenAtEnd
williamr@2: 			KErrNotReady when this method is called before completing previous RequestStop or AudioOutputStream
williamr@2: 			is already in the stopped state
williamr@2: 	
williamr@2: 	@see CMdaAudioOutputStream::KeepOpenAtEnd()
williamr@2: 	*/
williamr@2: 	IMPORT_C TInt RequestStop();
williamr@2: 
williamr@2: private:
williamr@2: 	CMdaAudioOutputStream();
williamr@2: private:
williamr@2: 	/**
williamr@2: 	This member is internal and not intended for use.
williamr@2: 	*/
williamr@2: 	CMMFMdaAudioOutputStream* iProperties;
williamr@2: 	};
williamr@2: 
williamr@2: #endif