epoc32/include/mdaaudiooutputstream.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000 (2010-03-16)
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     2
// All rights reserved.
williamr@2
     3
// This component and the accompanying materials are made available
williamr@2
     4
// 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
     5
// which accompanies this distribution, and is available
williamr@2
     6
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     7
//
williamr@2
     8
// Initial Contributors:
williamr@2
     9
// Nokia Corporation - initial contribution.
williamr@2
    10
//
williamr@2
    11
// Contributors:
williamr@2
    12
//
williamr@2
    13
// Description:
williamr@2
    14
//
williamr@2
    15
williamr@2
    16
#ifndef __MDAAUDIOOUTPUTSTREAM_H
williamr@2
    17
#define __MDAAUDIOOUTPUTSTREAM_H
williamr@2
    18
williamr@2
    19
williamr@2
    20
#include <e32std.h>
williamr@2
    21
#include <mmf/common/mmfbase.h>
williamr@2
    22
#include <mmf/common/mmfstandardcustomcommands.h>
williamr@2
    23
#include <mda/common/base.h>      
williamr@2
    24
#include <mda/client/utility.h>
williamr@2
    25
#include <mmf/common/mmfaudio.h>
williamr@2
    26
#include <mmfclntutility.h>
williamr@2
    27
williamr@2
    28
williamr@2
    29
/**
williamr@2
    30
@publishedAll
williamr@2
    31
@released
williamr@2
    32
williamr@2
    33
An interface class that notifies the client of the progress of audio output streaming.
williamr@2
    34
williamr@2
    35
It must be implemented by users of the CMdaAudioOutputStream class.
williamr@2
    36
williamr@2
    37
An object that implements this interface is passed to CMdaAudioOutputStream::NewL().
williamr@2
    38
*/
williamr@2
    39
class MMdaAudioOutputStreamCallback 
williamr@2
    40
	{
williamr@2
    41
public:
williamr@2
    42
williamr@2
    43
	/**
williamr@2
    44
	A callback function that is called when CMdaAudioOutputStream::Open() has completed, indicating that the
williamr@2
    45
	audio output stream is ready for use.
williamr@2
    46
williamr@2
    47
	@param  aError
williamr@2
    48
	        An error value which indicates if open was completed successfully. KErrNone if succeeded.
williamr@2
    49
	*/
williamr@2
    50
	virtual void MaoscOpenComplete(TInt aError) = 0;
williamr@2
    51
williamr@2
    52
	/**
williamr@2
    53
	A callback function that is called when a descriptor has been copied to the lower layers of MMF. 
williamr@2
    54
williamr@2
    55
	It is also called when an error has occurred or when the client has stopped the stream playing before the descriptor 
williamr@2
    56
	has been fully copied (by calling CMdaAudioOutputStream::Stop()).
williamr@2
    57
williamr@2
    58
	This function indicates to the client that it is safe to destroy the buffer passed to CMdaAudioOutputStream::WriteL(). 
williamr@2
    59
	It can also be used to make the next call to WriteL().
williamr@2
    60
williamr@2
    61
	@param  aError
williamr@2
    62
	        KErrNone if the copy succeeded, otherwise one of the system error codes. KErrAbort indicates that 
williamr@2
    63
	        the client has stopped the stream playing before the descriptor has been copied.
williamr@2
    64
	@param  aBuffer
williamr@2
    65
	        A reference to the buffer that has been copied.
williamr@2
    66
	*/
williamr@2
    67
	virtual void MaoscBufferCopied(TInt aError, const TDesC8& aBuffer) = 0;
williamr@2
    68
williamr@2
    69
	/**
williamr@2
    70
	A callback function that is called when playback terminates as a result of a CMdaAudioOutputStream::Stop().
williamr@2
    71
williamr@2
    72
	If the end of the sound data has been reached, the function returns KErrUnderFlow. If playback terminates for any 
williamr@2
    73
	other reason, the function returns an appropriate error value.
williamr@2
    74
williamr@2
    75
	@param  aError
williamr@2
    76
	        An error value which indicates play success or not. KErrNone if the close succeeded, otherwise one of the
williamr@2
    77
	        system error codes.
williamr@2
    78
	*/
williamr@2
    79
	virtual void MaoscPlayComplete(TInt aError) = 0;
williamr@2
    80
	};
williamr@2
    81
williamr@2
    82
williamr@2
    83
class CMMFMdaAudioOutputStream;
williamr@2
    84
williamr@2
    85
/**
williamr@2
    86
@publishedAll
williamr@2
    87
@released
williamr@2
    88
williamr@2
    89
The interface to an audio stream player passing raw audio data from specified buffers to the audio hardware.
williamr@2
    90
williamr@2
    91
This class enables MMF clients to:
williamr@2
    92
williamr@2
    93
Stream raw audio data to the audio hardware from specified buffers
williamr@2
    94
williamr@2
    95
Specify the priority of the audio stream in relation to other clients that may request to use the same audio hardware
williamr@2
    96
williamr@2
    97
Set the sample rate and the number of channels after successfully opening the stream. It is not possible to change these 
williamr@2
    98
values once  streaming has started.
williamr@2
    99
williamr@2
   100
Change the volume and balance before or while the stream is open for writing. Volume and balance settings take effect immediately.
williamr@2
   101
williamr@2
   102
The API supports callbacks from the server to notify the client:
williamr@2
   103
williamr@2
   104
MaoscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the
williamr@2
   105
audio hardware as a result of a previous call to Open().
williamr@2
   106
williamr@2
   107
MaoscBufferCopied() will be called each time audio data has been successfully copied to the lower layers of the
williamr@2
   108
MMF as a result of a previous WriteL().
williamr@2
   109
williamr@2
   110
MaoscPlayComplete() will be called when the audio data stream has been closed as a result of a previous Stop().
williamr@2
   111
*/
williamr@2
   112
class CMdaAudioOutputStream : public CBase,
williamr@2
   113
							  public MMMFClientUtility
williamr@2
   114
	{
williamr@2
   115
public:
williamr@2
   116
williamr@2
   117
	/**
williamr@2
   118
	Allocates and constructs an audio stream player object.
williamr@2
   119
williamr@2
   120
	@param  aCallBack
williamr@2
   121
	        A callback to notify the client when the sound device is open and ready to receive data, when 
williamr@2
   122
	        each descriptor has been copied and when the stream is closed. The caller must create a 
williamr@2
   123
	        callback class which implements this interface.
williamr@2
   124
	@param  aServer
williamr@2
   125
	        A pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided 
williamr@2
   126
	        for backward compatibility.
williamr@2
   127
williamr@2
   128
	@return A pointer to new audio stream player.
williamr@2
   129
	*/
williamr@2
   130
	IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,
williamr@2
   131
												CMdaServer* aServer = NULL);
williamr@2
   132
williamr@2
   133
	/**
williamr@2
   134
	Constructs and initialises a new instance of an audio streaming object.
williamr@2
   135
williamr@2
   136
	The function leaves if the audio streaming object cannot be created.
williamr@2
   137
williamr@2
   138
	@param  aCallBack
williamr@2
   139
	        A callback to notify the client when the sound device is open and ready to receive data, when each
williamr@2
   140
	        descriptor has been copied and when the stream is closed. The caller must create a callback class
williamr@2
   141
	        which implements this interface.
williamr@2
   142
	@param  aPriority
williamr@2
   143
	        This client's relative priority. This is a value between EMdaPriorityMin and EMdaPriorityMax and represents
williamr@2
   144
	        a relative priority. A higher value indicates a more important request.
williamr@2
   145
	@param  aPref
williamr@2
   146
	        The required behaviour if a higher priority client takes over the sound output device.
williamr@2
   147
williamr@2
   148
	@return A pointer to CMdaAudioOutputStream.
williamr@2
   149
williamr@2
   150
	@capability MultimediaDD
williamr@2
   151
	            A process requesting or using this method that has MultimediaDD capability will
williamr@2
   152
				always have precedence over a process that does not have MultimediaDD.
williamr@2
   153
	*/
williamr@2
   154
	IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,
williamr@2
   155
												TInt aPriority,
williamr@2
   156
												TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality);
williamr@2
   157
williamr@2
   158
williamr@2
   159
	/**
williamr@2
   160
    Destructor.
williamr@2
   161
williamr@2
   162
	Frees all resources owned by the object prior to its destruction.
williamr@2
   163
	*/
williamr@2
   164
	~CMdaAudioOutputStream();
williamr@2
   165
williamr@2
   166
	/**
williamr@2
   167
	Sets the sample rate and number of audio channels.
williamr@2
   168
williamr@2
   169
	@param  aSampleRate
williamr@2
   170
	        The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
williamr@2
   171
	@param  aChannels
williamr@2
   172
	        The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
williamr@2
   173
	
williamr@2
   174
	*/
williamr@2
   175
	virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);
williamr@2
   176
williamr@2
   177
	/**
williamr@2
   178
	Opens an output audio stream package.
williamr@2
   179
williamr@2
   180
	The MMdaAudioOutputStreamCallback::MaoscOpenComplete() callback function is called when the stream has been 
williamr@2
   181
	opened and is ready to receive audio data. If the open was unsuccessful, this is indicated by the aError 
williamr@2
   182
	parameter of the callback.
williamr@2
   183
williamr@2
   184
williamr@2
   185
	@param  aSettings
williamr@2
   186
	        A pointer to a TMdaPackage object.
williamr@2
   187
	
williamr@2
   188
	*/
williamr@2
   189
	virtual void Open(TMdaPackage* aSettings);
williamr@2
   190
williamr@2
   191
	/**
williamr@2
   192
	Returns the maximum volume level.
williamr@2
   193
williamr@2
   194
	@return The maximum volume level supported by the sound device, as an integer.
williamr@2
   195
	*/
williamr@2
   196
	virtual TInt MaxVolume();
williamr@2
   197
williamr@2
   198
	/**
williamr@2
   199
	Returns the current volume.
williamr@2
   200
williamr@2
   201
	@return The current volume as an integer.
williamr@2
   202
	*/
williamr@2
   203
	virtual TInt Volume();
williamr@2
   204
williamr@2
   205
	/**
williamr@2
   206
	Sets the audio volume.
williamr@2
   207
williamr@2
   208
	Set the volume to zero for "sound off" or any other value between 1 and MaxVolume().
williamr@2
   209
williamr@2
   210
	@param  aNewVolume
williamr@2
   211
	        A specified audio volume.
williamr@2
   212
williamr@2
   213
	*/
williamr@2
   214
	virtual void SetVolume(const TInt aNewVolume);
williamr@2
   215
williamr@2
   216
	/**
williamr@2
   217
	Sets the audio priority values.
williamr@2
   218
williamr@2
   219
	This function cannot be used while the stream object is open. It is intended for use before an Open() 
williamr@2
   220
	is issued, or between a previous Stop() and a new Open().
williamr@2
   221
williamr@2
   222
	@param  aPriority
williamr@2
   223
	        The priority level to apply, EMdaPriorityMin allows the client can be interrupted by any other client,
williamr@2
   224
	        EMdaPriorityNormal allows the client is only interrupted by clients with a higher priority or
williamr@2
   225
			EMdaPriorityMax allows the client cannot be interrupted by other clients.
williamr@2
   226
	@param  aPref
williamr@2
   227
	        A set of priority values that define the behaviour to be adopted by a client using a sound device if a 
williamr@2
   228
	        higher priority client takes over that device.
williamr@2
   229
williamr@2
   230
williamr@2
   231
	@capability MultimediaDD
williamr@2
   232
	            A process requesting or using this method that has MultimediaDD capability will
williamr@2
   233
				always have precedence over a process that does not have MultimediaDD.
williamr@2
   234
	*/
williamr@2
   235
	virtual void SetPriority(TInt aPriority, TMdaPriorityPreference aPref);
williamr@2
   236
	
williamr@2
   237
	/**
williamr@2
   238
	Writes (plays) streaming raw audio data.
williamr@2
   239
williamr@2
   240
	This function is asynchronous. When aData has been received, the client is notified by a call to 
williamr@2
   241
	MMdaAudioOutputStreamCallback::MaoscBufferCopied(). The client can call WriteL() again before this notification 
williamr@2
   242
	takes place because the buffers are maintained in a client-side queue until they have been sent. An active object 
williamr@2
   243
	performs the notification, and copies the next item in the queue to the server.
williamr@2
   244
	MMdaAudioOutputStreamCallback::MaoscPlayComplete() is called when all descriptors have been sent.
williamr@2
   245
williamr@2
   246
	@param  aData
williamr@2
   247
	        A reference to the stream data.
williamr@2
   248
williamr@2
   249
	*/
williamr@2
   250
	virtual void WriteL(const TDesC8& aData);
williamr@2
   251
williamr@2
   252
	/**
williamr@2
   253
	Stops writing data to a stream.
williamr@2
   254
williamr@2
   255
	*/
williamr@2
   256
	virtual void Stop();
williamr@2
   257
williamr@2
   258
	/**
williamr@2
   259
	Pause data rendering by audio hardware.
williamr@2
   260
	@return  An error code indicating if the operation was successful. KErrNone on success, 
williamr@2
   261
		KErrNotReady if not streaming
williamr@2
   262
		KErrNotSupported if trying to pause when resume is not supported by DevSound
williamr@2
   263
	*/
williamr@2
   264
williamr@2
   265
	IMPORT_C TInt Pause();
williamr@2
   266
williamr@2
   267
williamr@2
   268
	/**
williamr@2
   269
	Resume data rendering by audio hardware.
williamr@2
   270
	@return  An error code indicating if the operation was successful. KErrNone on success, 
williamr@2
   271
		KErrNotReady if not paused. 
williamr@2
   272
		KErrNotSupported if trying to resume when resume is not supported by DevSound
williamr@2
   273
	*/
williamr@2
   274
	IMPORT_C TInt Resume();
williamr@2
   275
williamr@2
   276
williamr@2
   277
	/**
williamr@2
   278
	Returns the current position within the data stream.
williamr@2
   279
williamr@2
   280
	@return The current position within the stream in microseconds.
williamr@2
   281
	*/
williamr@2
   282
	virtual const TTimeIntervalMicroSeconds& Position();
williamr@2
   283
williamr@2
   284
	/**
williamr@2
   285
	Sets the audio balance.
williamr@2
   286
williamr@2
   287
	@param  aBalance
williamr@2
   288
	        A specified balance volume. Default is KMMFBalanceCenter.
williamr@2
   289
williamr@2
   290
	*/
williamr@2
   291
	IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);
williamr@2
   292
	
williamr@2
   293
	/**
williamr@2
   294
	Returns the current balance as an integer.
williamr@2
   295
williamr@2
   296
	@return The current balance value as integer.
williamr@2
   297
	*/
williamr@2
   298
	IMPORT_C TInt GetBalanceL() const;
williamr@2
   299
williamr@2
   300
	/**
williamr@2
   301
	Returns the current number of bytes rendered by audio hardware.
williamr@2
   302
williamr@2
   303
	@return The current current number of bytes rendered by audio hardware as an integer.
williamr@2
   304
	*/
williamr@2
   305
	IMPORT_C TInt GetBytes();
williamr@2
   306
williamr@2
   307
	/**
williamr@2
   308
    Sets the data type.  If the data type is not explicitly set it will assumed to be pcm16.
williamr@2
   309
    If it is set then the hardware must support the data type being set otherwise the 
williamr@2
   310
    function leaves with KErrNotSupported.
williamr@2
   311
    
williamr@2
   312
    @param	aAudioType The fourCC code used to specify the data type of the streamed audio
williamr@2
   313
williamr@2
   314
	@leave KErrNotSupported
williamr@2
   315
	       Leaves with this for any unsuported data type.
williamr@2
   316
	*/
williamr@2
   317
    IMPORT_C void SetDataTypeL(TFourCC aAudioType);
williamr@2
   318
williamr@2
   319
	/**
williamr@2
   320
	Returns the current data type.
williamr@2
   321
williamr@2
   322
	@return The ID of the data type.
williamr@2
   323
	*/
williamr@2
   324
	IMPORT_C TFourCC DataType() const;
williamr@2
   325
	
williamr@2
   326
	/**
williamr@2
   327
	Registers the Event for Notification when resource is avaliable.
williamr@2
   328
	@param	aCallback
williamr@2
   329
	      	The audio outputstream observer interface..
williamr@2
   330
	@param 	aNotificationEventUid
williamr@2
   331
	 	The Event for which the client is registered.
williamr@2
   332
	@param 	aNotificationRegistrationData
williamr@2
   333
		Notification registration specific data.
williamr@2
   334
	@return An error code indicating if the registration was successful. KErrNone on success, 
williamr@2
   335
		otherwise another of the system-wide error codes.
williamr@2
   336
	*/
williamr@2
   337
	IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback& aCallback,TUid aNotificationEventUid,const TDesC8& aNotificationRegistrationData = KNullDesC8);
williamr@2
   338
	
williamr@2
   339
	/**
williamr@2
   340
	Cancels the registered notification event.
williamr@2
   341
	@param  aNotificationEventUid
williamr@2
   342
		The Event to notify the client.
williamr@2
   343
		
williamr@2
   344
	@return An error code indicating if the registration was successful. KErrNone on success, 
williamr@2
   345
		otherwise another of the system-wide error codes.
williamr@2
   346
	*/
williamr@2
   347
	IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);
williamr@2
   348
    
williamr@2
   349
    	/**
williamr@2
   350
	Waits for the client to resume the play even after the default timer expires.
williamr@2
   351
	@return An error code indicating if the registration was successful. KErrNone on success, 
williamr@2
   352
		otherwise another of the system-wide error codes.
williamr@2
   353
	*/
williamr@2
   354
	IMPORT_C TInt WillResumePlay();
williamr@2
   355
	
williamr@2
   356
	/**
williamr@2
   357
	Retrieves a custom interface to the underlying device.
williamr@2
   358
williamr@2
   359
	@param  aInterfaceId
williamr@2
   360
	        The interface UID, defined with the custom interface.
williamr@2
   361
	
williamr@2
   362
	@return A pointer to the interface implementation, or NULL if the device does not
williamr@2
   363
	        implement the interface requested. The return value must be cast to the
williamr@2
   364
	        correct type by the user.
williamr@2
   365
	*/
williamr@2
   366
	IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
williamr@2
   367
	
williamr@2
   368
	/**
williamr@2
   369
	When this method is called, AudioOutputStream goes into a different mode wherein it does not call 
williamr@2
   370
	MaoscPlayComplete() with KErrUnderflow when all the supplied data has been played. Instead client 
williamr@2
   371
	should signal the end of the play by calling RequestStop() or Stop() on AudioOutputStream.
williamr@2
   372
	If the client calls RequestStop(), AudioOutputStream waits until all the queued data has been played out
williamr@2
   373
	and then calls MaoscPlayComplete(). This behaviour is different from that of Stop(), which stops the play
williamr@2
   374
	immediately by discarding all the queued data.
williamr@2
   375
	
williamr@2
   376
	Client should call this method on CMdaAudioOutputStream just after its construction and its 
williamr@2
   377
	effect remains through out its lifetime.
williamr@2
   378
	
williamr@2
   379
	Note: This feature is supported only on a DevSound which ignores the underflow errors in the middle of
williamr@2
   380
	the play i.e which returns ETrue from QueryIgnoresUnderflow().
williamr@2
   381
	
williamr@2
   382
	@return KErrNone on success, 
williamr@2
   383
			KErrNotSupported if the underlying DevSound does not ignore the underflow errors in the middle of the play
williamr@2
   384
				
williamr@2
   385
	@see CMdaAudioOutputStream::RequestStop()
williamr@2
   386
	@see CMMFDevSound::QueryIgnoresUnderflow()
williamr@2
   387
	*/
williamr@2
   388
	IMPORT_C TInt KeepOpenAtEnd();
williamr@2
   389
	
williamr@2
   390
	/**
williamr@2
   391
	This method signals the end of play when the AudioOutputStream is in KeepOpenAtEnd mode i.e when client
williamr@2
   392
	makes KeepOpenAtEnd call on it. When RequestStop is called, AudioOutputStream completes playing all
williamr@2
   393
	the data that is supplied to it and calls MaoscPlayComplete() with KErrUnderflow.
williamr@2
   394
	
williamr@2
   395
	Note: Before calling this method, client must have already called KeepOpenAtEnd() successfully, Otherwise, this
williamr@2
   396
		  method returns KErrNotSupported. 
williamr@2
   397
		  It is recommended to use KeepOpenAtEnd and RequestStop calls to get a predictable behaviour during stopping.
williamr@2
   398
	
williamr@2
   399
	@return KErrNone on success
williamr@2
   400
			KErrNotSupported when this method is called without calling KeepOpenAtEnd
williamr@2
   401
			KErrNotReady when this method is called before completing previous RequestStop or AudioOutputStream
williamr@2
   402
			is already in the stopped state
williamr@2
   403
	
williamr@2
   404
	@see CMdaAudioOutputStream::KeepOpenAtEnd()
williamr@2
   405
	*/
williamr@2
   406
	IMPORT_C TInt RequestStop();
williamr@2
   407
williamr@2
   408
private:
williamr@2
   409
	CMdaAudioOutputStream();
williamr@2
   410
private:
williamr@2
   411
	/**
williamr@2
   412
	This member is internal and not intended for use.
williamr@2
   413
	*/
williamr@2
   414
	CMMFMdaAudioOutputStream* iProperties;
williamr@2
   415
	};
williamr@2
   416
williamr@2
   417
#endif