1 mdaaudioinputstream.h

     1 

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

     3 // All rights reserved.

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

     5 // 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

     6 // which accompanies this distribution, and is available

     7 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 //

     9 // Initial Contributors:

    10 // Nokia Corporation - initial contribution.

    11 //

    12 // Contributors:

    13 //

    14 // Description:

    15 //

    16 

    17 

    18 

    19 #ifndef __MDAAUDIOINPUTSTREAM_H

    20 #define __MDAAUDIOINPUTSTREAM_H

    21 

    22 

    23 #include <e32std.h>

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

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

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

    27 #include <mmfclntutility.h>

    28 

    29 

    30 /**

    31 @publishedAll

    32 @released

    33 

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

    35 

    36 It must be implemented by users of the CMdaAudioInputStream class. 

    37 

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

    39 */

    40 class MMdaAudioInputStreamCallback 

    41 	{

    42 public:

    43 

    44 	/**

    45 	A callback function that is called when CMdaAudioInputStream::Open() has 

    46 	completed, indicating that the audio input stream is ready for use.

    47 

    48 	@param  aError

    49 	        An error value which indicates if open was successful or not. KErrNone if the open succeeded,

    50 	        otherwise one of the system error codes.

    51 

    52 	*/

    53 	virtual void MaiscOpenComplete(TInt aError) = 0;

    54 

    55 	/**

    56 	A callback function that is called when a chunk of audio data has been copied to the descriptor specified 

    57 	in a CMdaAudioInputStream::ReadL().

    58 

    59 	It is also called as part of a 'cleanup' operation when CMdaAudioInputStream::Stop() is used. In such circumstances, 

    60 	the remaining audio data in the FIFO since the last ReadL() and the Stop() command is returned. In addition aError 

    61 	is set to KErrAbort.

    62 

    63 	Use this callback to retrieve the pointers to your recorded data and to issue subsequent ReadL() calls, and be prepared 

    64 	to shut down you recording functions if KErrAbort (input stream closed) is returned in aError.

    65 

    66 	@param aError

    67 	       An error value indicating if the copy was successful. KErrNone if the copy succeeded, KErrAbort if the input stream 

    68 	       was closed for some reason, otherwise one of the system error codes.

    69 	@param aBuffer

    70 	       A reference to the buffer that has been copied.

    71 	*/

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

    73 

    74 	/**

    75 	A callback function that is called when the input stream is closed using CMdaAudioInputStream::Stop(). 

    76 

    77 	This callback is usually 'paired' with a MaiscBufferCopied() that returns the last remaining audio data

    78 	in the FIFO between the last CMdaAudioInputStream::ReadL() and the Stop() command.

    79 

    80 	@param aError

    81 	       An error value indicating if the record was successful. KErrNone if the stop succeeded, otherwise one

    82 	       of the system error codes.

    83 	*/

    84 	virtual void MaiscRecordComplete(TInt aError) = 0;

    85 	};

    86 

    87 

    88 class CMMFMdaAudioInputStream;

    89 

    90 /**

    91 @publishedAll

    92 @released

    93 

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

    95 

    96 This class enables MMF clients to:

    97 

    98 Stream raw audio data from the audio hardware to specified buffers.

    99 

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

   101 

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

   103 change these values once streaming has started.

   104 

   105 Change the gain and balance before or while streaming is in progress. Gain and balance settings take effect immediately.

   106 

   107 

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

   109 

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

   111 user as a result of a previous call to Open().

   112 

   113 MaiscBufferCopied() will be called multiple times while the FIFO (queued via ReadL()) is emptied.

   114 Note: Each buffer will be flagged with KErrAbort if received after Stop() on is called. MaiscRecordComplete is called

   115 once all remaining buffers have been read.

   116 

   117 

   118 MaiscRecordComplete() is called after Stop() has been called. aError - KErrAbort if MaiscRecordComplete called

   119 as a result of a call to Stop().

   120 

   121 Users of object CMdaAudioInputStream should ensure that implementation of the callback methods MaiscOpenComplete,MaiscBufferCopied 

   122 and MaiscRecordComplete in class MMdaAudioInputStreamCallback do not delete the object,otherwise a Kern-Exec 3 would occur during callback.

   123 */

   124 class CMdaAudioInputStream : public CBase,

   125 							 public MMMFClientUtility	

   126 {

   127 public:

   128 

   129 	/**

   130 	Instantiates a new audio input stream using default priority preferences.

   131 

   132 	@param  aCallBack

   133 	        A callback to notify the client when the input stream has been initialised and is ready 

   134 	        for use, when data has been copied to a specified descriptor and when input streaming is 

   135 	        stopped. The caller must create a callback class that implements this interface.

   136 

   137 	@return A pointer to the audio input stream object.

   138 	

   139 	@capability	UserEnvironment

   140 			For recording - the requesting client process must have a 

   141 			UserEnvironment capability.

   142 	*/

   143 	IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback& aCallBack);

   144 

   145 	/**

   146 	Instantiates a new audio input stream.

   147 

   148 	@param  aCallBack

   149 	        A callback to notify the client when the input stream has been initialised and is ready for 

   150 	        use. The caller must create a callback class which implements this interface.

   151 	@param  aPriority

   152 	        This client's relative priority. This is a value between EMdaPriorityMin and EMdaPriorityMax and 

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

   154 	@param  aPref

   155 	        The required behaviour if a higher priority client takes over the sound output device.

   156 

   157 	@return A pointer to the audio input stream object.

   158 

   159 	@capability MultimediaDD

   160 	            A process requesting or using this method that has MultimediaDD capability will

   161 				always have precedence over a process that does not have MultimediaDD.

   162 	            

   163 	@capability	UserEnvironment

   164 			For recording - the requesting client process must have a 

   165 			UserEnvironment capability.

   166 	*/

   167 	IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback& aCallBack,

   168 		TInt aPriority,	TMdaPriorityPreference aPref);

   169 

   170 	/**

   171     Destructor.

   172 

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

   174 	*/

   175 	~CMdaAudioInputStream();

   176 

   177 	/**

   178 	Sets the sample rate and number of audio channels.

   179 

   180 	@param  aSampleRate

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

   182 	@param  aChannels

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

   184 	*/

   185 	IMPORT_C void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);

   186 

   187 	/**

   188 	Opens an input audio stream package.

   189 

   190 	The MMdaAudioInputStreamCallback::MaisOpenComplete() callback function is called when the stream has been 

   191 	opened and is ready to record data. If the open was unsuccessful, this is indicated by the aError parameter 

   192 	of the callback.

   193 

   194 	@param  aSettings

   195 	        A pointer to an TMdaPackage object.

   196 	*/

   197 	IMPORT_C void Open(TMdaPackage* aSettings);

   198 

   199 	/**

   200 	Sets the gain for the audio device to a specified value.

   201 

   202 	@param  aNewGain

   203 	        The gain setting. This can be any value from zero to the value returned by a call to 

   204 	        MaxGain(). A value which is less than zero is set to zero. A value which is greater 

   205 	        than MaxGain() is set to MaxGain().

   206 	*/

   207 	IMPORT_C void SetGain(TInt aNewGain);

   208 

   209 	/**

   210 	Returns the current gain setting.

   211 

   212 	@return The current gain setting.

   213 	*/

   214 	IMPORT_C TInt Gain() const;

   215 

   216 	/**

   217 	Returns the maximum gain level.

   218 

   219 	@return The maximum gain value that is supported by the sound device.

   220 	*/

   221 	IMPORT_C TInt MaxGain() const;

   222 

   223 	/**

   224 	Sets the current audio balance.

   225 

   226 	The balance can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight, the default value 

   227 	being KMMFBalanceCenter.

   228 

   229 	@param  aBalance

   230 	        A specified balance value.

   231 	*/

   232 	IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);

   233 

   234 	/**

   235 	Returns the current audio balance.

   236 

   237 	@return The current balance value.

   238 	*/

   239 	IMPORT_C TInt GetBalanceL() const;

   240 

   241 	/**

   242 	Sets the audio priority values.

   243 

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

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

   246 

   247 	@param  aPriority

   248 	        The priority level to apply, EMdaPriorityMin means the client can be interrupted by any other client, EMdaPriorityNormal

   249 	        means the client is only interrupted by clients with a higher priority and EMdaPriorityMax means the client cannot be interrupted by

   250 	        other clients.

   251 	@param  aPref

   252 	        A set of priority values that define the behaviour to be adopted by a client using a sound device if a higher priority

   253 	        client takes over that device.

   254 

   255 	@capability MultimediaDD

   256 	            A process requesting or using this method that has MultimediaDD capability will

   257 				always have precedence over a process that does not have MultimediaDD.

   258 	*/

   259 	IMPORT_C void SetPriority(TInt aPriority, TMdaPriorityPreference aPref);

   260 

   261 	/**

   262 	Records streaming raw audio data.

   263 

   264 	If this is the first ReadL() after a successful Open() this function starts the audio recording process.

   265 

   266 	The MMdaAudioInputStreamCallback::MaisBufferCopied() callback function is called when the buffer has been successfully 

   267 	filled. A pointer to the newly filled buffer is returned in the callback.

   268 

   269 	Note: The MMdaAudioInputStreamCallback::MaisBufferCopied() callback function is also called when a Stop() is issued, with a 

   270 	pointer to the remaining recorded audio data and the aError parameter of the callback set to indicate recording has finished.

   271 

   272 	@param  aData

   273 	        A reference to a buffer to be written into.

   274 	*/

   275 	IMPORT_C void ReadL(TDes8& aData);

   276 

   277 	/**

   278 	Stops the recording process.

   279 

   280 	The MMdaAudioInputStreamCallback::MaisRecordComplete() callback function is called when recording has been halted. Just prior 

   281 	to issuing this callback, the FIFO buffers are read and the remaining audio data passed back by a final 

   282 	MMdaAudioInputStreamCallback::MaisBufferCopied() callback with its aError parameter set to KErrAbort.

   283 	

   284 	Any remaining FIFO buffers are also passed back, with their aError parameter set to KErrAbort.

   285 	

   286 	Stop is immediate and best used for premature stops, for example within destructors.

   287 	If it is critical to receive all data buffers upto the point that Recording has Stopped, 

   288 	we recommend using RequestStop instead. Otherwise some trailing buffers may be lost from the recording process.

   289 	

   290 	If a Stop is issued after a RequestStop, Stop will take precedent.

   291 

   292 	@see CMdaAudioInputStream::RequestStop()

   293 	*/

   294 	IMPORT_C void Stop();

   295 

   296 	/**

   297 	Returns the current position within the data stream in microseconds since the start of streaming.

   298 

   299 	@return The current position.

   300 	*/

   301 	IMPORT_C const TTimeIntervalMicroSeconds& Position();

   302 

   303 	/**

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

   305 

   306 	@return The number of bytes.

   307 	*/

   308 	IMPORT_C TInt GetBytes();

   309 

   310 

   311 	/**

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

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

   314     function leaves with KErrNotSupported.

   315     

   316     @param	aAudioType The fourCC code used to request the data type of the recorded data.

   317 

   318 	@leave  KErrNotSupported

   319 	        Leaves with this for any unsuported data type.

   320 	*/

   321 	IMPORT_C void SetDataTypeL(TFourCC aAudioType);

   322 

   323 	/**

   324 	Returns the current data type.

   325 

   326 	@return The ID of the data type.

   327 	*/

   328 	IMPORT_C TFourCC DataType() const;

   329 	

   330 	/**

   331 	Returns the bit rates supported by the sound device

   332 	

   333 	@param  aSupportedBitRates

   334 	@leave KErrNotSupported

   335 		If the sound device does not support setting the bit rate

   336 	The supported bit rates, in bits per second, shall be appended to this array. Note that 

   337 	the array shall be reset by this method.

   338 	*/

   339 	IMPORT_C void GetSupportedBitRatesL(RArray<TInt>& aSupportedBitRates);

   340 	/**

   341 	Returns the current bit rate.

   342 	@return The current bit rate, in bits per second.

   343 	@leave KErrNotSupported

   344 		If the sound device does not support returning the current bit rate

   345 	*/

   346 	IMPORT_C TInt BitRateL() const;

   347 	/**

   348 	Sets the bit rate to a new value.

   349 	@param  aBitRate

   350 		The new bit rate, in bits per second.

   351 	@leave KErrNotSupported

   352 		If the sound device does not support returning the current bit rate or the bit rate set is not supported

   353 	*/

   354 	IMPORT_C void SetBitRateL(TInt aBitRate);

   355 	

   356 	/**

   357 	Retrieves a custom interface to the underlying device.

   358 

   359 	@param  aInterfaceId

   360 	        The interface UID, defined with the custom interface.

   361 	

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

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

   364 	        correct type by the user.

   365 	*/

   366 	IMPORT_C TAny* CustomInterface(TUid aInterfaceId);

   367 

   368 	/**

   369 	Indicates that the client wishes to use a single buffer	to collect the data. 

   370 	This buffer is passed via the ReadL api.

   371 	

   372 	@param	aSingleMode

   373 			ETrue to indicate setting of single buffer mode and the use of a single 

   374 			buffer, EFalse to indicate use of multiple buffers.

   375 	*/

   376 	IMPORT_C void SetSingleBufferMode(TBool aSingleMode);

   377 

   378 	/**

   379 	Requests a Stop of the recording process.

   380 

   381 	The device is requested to Stop and does so after all unprocessed buffers are processed and passed

   382 	back to the input stream. The device is actually Stopped when the final empty buffer indicating 

   383 	buffer process completion is received.

   384 

   385 	@see CMdaAudioInputStream::Stop()

   386 	*/

   387 	IMPORT_C void RequestStop();

   388 

   389 private:

   390 	CMdaAudioInputStream();

   391 private:

   392 	CMMFMdaAudioInputStream* iProperties;

   393 	};

   394 

   395 #endif