epoc32/include/mdaaudiooutputstream.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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