|
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 "Eclipse Public License v1.0" |
|
6 // which accompanies this distribution, and is available |
|
7 // at the URL "http://www.eclipse.org/legal/epl-v10.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 The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and |
|
153 EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request. |
|
154 @param aPref |
|
155 The Priority Preference - an additional audio policy parameter. The suggested default is |
|
156 EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional |
|
157 values may be supported by given phones and/or platforms, but should not be depended upon by |
|
158 portable code. |
|
159 |
|
160 @return A pointer to the audio input stream object. |
|
161 |
|
162 @capability UserEnvironment |
|
163 For recording - the requesting client process must have a |
|
164 UserEnvironment capability. |
|
165 |
|
166 Note: The Priority Value and Priority Preference are used primarily when deciding what to do when |
|
167 several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference, |
|
168 the adaptation may consider other parameters such as the SecureId and Capabilities of the client process. |
|
169 Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may |
|
170 vary between different phones. Portable applications are advised not to assume any specific behaviour. |
|
171 */ |
|
172 IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback& aCallBack, |
|
173 TInt aPriority, TInt aPref); |
|
174 |
|
175 /** |
|
176 Destructor. |
|
177 |
|
178 Frees all resources owned by the object prior to its destruction. |
|
179 */ |
|
180 ~CMdaAudioInputStream(); |
|
181 |
|
182 /** |
|
183 Sets the sample rate and number of audio channels. |
|
184 |
|
185 @param aSampleRate |
|
186 The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings. |
|
187 @param aChannels |
|
188 The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings. |
|
189 */ |
|
190 IMPORT_C void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels); |
|
191 |
|
192 /** |
|
193 Opens an input audio stream package. |
|
194 |
|
195 The MMdaAudioInputStreamCallback::MaisOpenComplete() callback function is called when the stream has been |
|
196 opened and is ready to record data. If the open was unsuccessful, this is indicated by the aError parameter |
|
197 of the callback. |
|
198 |
|
199 @param aSettings |
|
200 A pointer to an TMdaPackage object. |
|
201 */ |
|
202 IMPORT_C void Open(TMdaPackage* aSettings); |
|
203 |
|
204 /** |
|
205 Sets the gain for the audio device to a specified value. |
|
206 |
|
207 @param aNewGain |
|
208 The gain setting. This can be any value from zero to the value returned by a call to |
|
209 MaxGain(). A value which is less than zero is set to zero. A value which is greater |
|
210 than MaxGain() is set to MaxGain(). |
|
211 */ |
|
212 IMPORT_C void SetGain(TInt aNewGain); |
|
213 |
|
214 /** |
|
215 Returns the current gain setting. |
|
216 |
|
217 @return The current gain setting. |
|
218 */ |
|
219 IMPORT_C TInt Gain() const; |
|
220 |
|
221 /** |
|
222 Returns the maximum gain level. |
|
223 |
|
224 @return The maximum gain value that is supported by the sound device. |
|
225 */ |
|
226 IMPORT_C TInt MaxGain() const; |
|
227 |
|
228 /** |
|
229 Sets the current audio balance. |
|
230 |
|
231 The balance can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight, the default value |
|
232 being KMMFBalanceCenter. |
|
233 |
|
234 @param aBalance |
|
235 A specified balance value. |
|
236 */ |
|
237 IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter); |
|
238 |
|
239 /** |
|
240 Returns the current audio balance. |
|
241 |
|
242 @return The current balance value. |
|
243 */ |
|
244 IMPORT_C TInt GetBalanceL() const; |
|
245 |
|
246 /** |
|
247 Sets the audio priority values. |
|
248 |
|
249 This function cannot be used while the stream object is open. It is intended for use before an Open() |
|
250 is issued, or between a previous Stop() and a new Open(). |
|
251 |
|
252 @param aPriority |
|
253 The Priority Value. |
|
254 @param aPref |
|
255 The Priority Preference. |
|
256 |
|
257 @see CMdaAudioInputStream::NewL() |
|
258 */ |
|
259 IMPORT_C void SetPriority(TInt aPriority, TInt 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 |