1 // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #ifndef __MDAAUDIOOUTPUTSTREAM_H

    17 #define __MDAAUDIOOUTPUTSTREAM_H

    18 

    19 

    20 #include <e32std.h>

    21 #include <mmf/common/mmfbase.h>

    22 #include <mmf/common/mmfstandardcustomcommands.h>

    23 #include <mda/common/base.h>      

    24 #include <mda/client/utility.h>

    25 #include <mmf/common/mmfaudio.h>

    26 #include <mmfclntutility.h>

    27 

    28 

    29 /**

    30 @publishedAll

    31 @released

    32 

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

    34 

    35 It must be implemented by users of the CMdaAudioOutputStream class.

    36 

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

    38 */

    39 class MMdaAudioOutputStreamCallback 

    40 	{

    41 public:

    42 

    43 	/**

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

    45 	audio output stream is ready for use.

    46 

    47 	@param  aError

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

    49 	*/

    50 	virtual void MaoscOpenComplete(TInt aError) = 0;

    51 

    52 	/**

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

    54 

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

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

    57 

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

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

    60 

    61 	@param  aError

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

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

    64 	@param  aBuffer

    65 	        A reference to the buffer that has been copied.

    66 	*/

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

    68 

    69 	/**

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

    71 

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

    73 	other reason, the function returns an appropriate error value.

    74 

    75 	@param  aError

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

    77 	        system error codes.

    78 	*/

    79 	virtual void MaoscPlayComplete(TInt aError) = 0;

    80 	};

    81 

    82 

    83 class CMMFMdaAudioOutputStream;

    84 

    85 /**

    86 @publishedAll

    87 @released

    88 

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

    90 

    91 This class enables MMF clients to:

    92 

    93 Stream raw audio data to the audio hardware from specified buffers

    94 

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

    96 

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

    98 values once  streaming has started.

    99 

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

   101 

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

   103 

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

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

   106 

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

   108 MMF as a result of a previous WriteL().

   109 

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

   111 */

   112 class CMdaAudioOutputStream : public CBase,

   113 							  public MMMFClientUtility

   114 	{

   115 public:

   116 

   117 	/**

   118 	Allocates and constructs an audio stream player object.

   119 

   120 	@param  aCallBack

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

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

   123 	        callback class which implements this interface.

   124 	@param  aServer

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

   126 	        for backward compatibility.

   127 

   128 	@return A pointer to new audio stream player.

   129 	*/

   130 	IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,

   131 												CMdaServer* aServer = NULL);

   132 

   133 	/**

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

   135 

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

   137 

   138 	@param  aCallBack

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

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

   141 	        which implements this interface.

   142     @param  aPriority

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

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

   145     @param  aPref

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

   147             EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional 

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

   149             portable code.

   150 

   151 	@return A pointer to CMdaAudioOutputStream.

   152 

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

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

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

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

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

   158 	*/

   159 	IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,

   160 												TInt aPriority,

   161 												TInt aPref = EMdaPriorityPreferenceTimeAndQuality);

   162 

   163 

   164 	/**

   165     Destructor.

   166 

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

   168 	*/

   169 	~CMdaAudioOutputStream();

   170 

   171 	/**

   172 	Sets the sample rate and number of audio channels.

   173 

   174 	@param  aSampleRate

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

   176 	@param  aChannels

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

   178 	

   179 	*/

   180 	virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);

   181 

   182 	/**

   183 	Opens an output audio stream package.

   184 

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

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

   187 	parameter of the callback.

   188 

   189 

   190 	@param  aSettings

   191 	        A pointer to a TMdaPackage object.

   192 	

   193 	*/

   194 	virtual void Open(TMdaPackage* aSettings);

   195 

   196 	/**

   197 	Returns the maximum volume level.

   198 

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

   200 	*/

   201 	virtual TInt MaxVolume();

   202 

   203 	/**

   204 	Returns the current volume.

   205 

   206 	@return The current volume as an integer.

   207 	*/

   208 	virtual TInt Volume();

   209 

   210 	/**

   211 	Sets the audio volume.

   212 

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

   214 

   215 	@param  aNewVolume

   216 	        A specified audio volume.

   217 

   218 	*/

   219 	virtual void SetVolume(const TInt aNewVolume);

   220 

   221 	/**

   222 	Sets the audio priority values.

   223 

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

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

   226 

   227 	@param  aPriority

   228 	        The Priority Value.

   229 	@param  aPref

   230 	        The Priority Preference.

   231 

   232     @see CMdaAudioOutputStream::NewL()

   233 	*/

   234 	virtual void SetPriority(TInt aPriority, TInt aPref);

   235 	

   236 	/**

   237 	Writes (plays) streaming raw audio data.

   238 

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

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

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

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

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

   244 

   245 	@param  aData

   246 	        A reference to the stream data.

   247 

   248 	*/

   249 	virtual void WriteL(const TDesC8& aData);

   250 

   251 	/**

   252 	Stops writing data to a stream.

   253 

   254 	*/

   255 	virtual void Stop();

   256 

   257 	/**

   258 	Pause data rendering by audio hardware.

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

   260 		KErrNotReady if not streaming

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

   262 	*/

   263 

   264 	IMPORT_C TInt Pause();

   265 

   266 

   267 	/**

   268 	Resume data rendering by audio hardware.

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

   270 		KErrNotReady if not paused. 

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

   272 	*/

   273 	IMPORT_C TInt Resume();

   274 

   275 

   276 	/**

   277 	Returns the current position within the data stream.

   278 

   279 	@return The current position within the stream in microseconds.

   280 	*/

   281 	virtual const TTimeIntervalMicroSeconds& Position();

   282 

   283 	/**

   284 	Sets the audio balance.

   285 

   286 	@param  aBalance

   287 	        A specified balance volume. Default is KMMFBalanceCenter.

   288 

   289 	*/

   290 	IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);

   291 	

   292 	/**

   293 	Returns the current balance as an integer.

   294 

   295 	@return The current balance value as integer.

   296 	*/

   297 	IMPORT_C TInt GetBalanceL() const;

   298 

   299 	/**

   300 	Returns the current number of bytes rendered by audio hardware.

   301 

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

   303 	*/

   304 	IMPORT_C TInt GetBytes();

   305 

   306 	/**

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

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

   309     function leaves with KErrNotSupported.

   310     

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

   312 

   313 	@leave KErrNotSupported

   314 	       Leaves with this for any unsuported data type.

   315 	*/

   316     IMPORT_C void SetDataTypeL(TFourCC aAudioType);

   317 

   318 	/**

   319 	Returns the current data type.

   320 

   321 	@return The ID of the data type.

   322 	*/

   323 	IMPORT_C TFourCC DataType() const;

   324 	

   325 	/**

   326 	Registers the Event for Notification when resource is avaliable.

   327 	@param	aCallback

   328 	      	The audio outputstream observer interface..

   329 	@param 	aNotificationEventUid

   330 	 	The Event for which the client is registered.

   331 	@param 	aNotificationRegistrationData

   332 		Notification registration specific data.

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

   334 		otherwise another of the system-wide error codes.

   335 	*/

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

   337 	

   338 	/**

   339 	Cancels the registered notification event.

   340 	@param  aNotificationEventUid

   341 		The Event to notify the client.

   342 		

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

   344 		otherwise another of the system-wide error codes.

   345 	*/

   346 	IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);

   347     

   348     	/**

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

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

   351 		otherwise another of the system-wide error codes.

   352 	*/

   353 	IMPORT_C TInt WillResumePlay();

   354 	

   355 	/**

   356 	Retrieves a custom interface to the underlying device.

   357 

   358 	@param  aInterfaceId

   359 	        The interface UID, defined with the custom interface.

   360 	

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

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

   363 	        correct type by the user.

   364 	*/

   365 	IMPORT_C TAny* CustomInterface(TUid aInterfaceId);

   366 	

   367 	/**

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

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

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

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

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

   373 	immediately by discarding all the queued data.

   374 	

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

   376 	effect remains through out its lifetime.

   377 	

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

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

   380 	

   381 	@return KErrNone on success, 

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

   383 				

   384 	@see CMdaAudioOutputStream::RequestStop()

   385 	@see CMMFDevSound::QueryIgnoresUnderflow()

   386 	*/

   387 	IMPORT_C TInt KeepOpenAtEnd();

   388 	

   389 	/**

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

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

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

   393 	

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

   395 		  method returns KErrNotSupported. 

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

   397 	

   398 	@return KErrNone on success

   399 			KErrNotSupported when this method is called without calling KeepOpenAtEnd

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

   401 			is already in the stopped state

   402 	

   403 	@see CMdaAudioOutputStream::KeepOpenAtEnd()

   404 	*/

   405 	IMPORT_C TInt RequestStop();

   406 

   407 private:

   408 	CMdaAudioOutputStream();

   409 private:

   410 	/**

   411 	This member is internal and not intended for use.

   412 	*/

   413 	CMMFMdaAudioOutputStream* iProperties;

   414 	};

   415 

   416 #endif