|
1 // Copyright (c) 2001-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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __SOUNDDEVICE_H__ |
|
17 #define __SOUNDDEVICE_H__ |
|
18 |
|
19 #include <e32base.h> |
|
20 #include <f32file.h> |
|
21 #include <mmf/common/mmfbase.h> |
|
22 #include <mmf/common/mmfutilities.h> |
|
23 #include <mmf/common/mmfcontroller.h> |
|
24 |
|
25 |
|
26 //Debugging info |
|
27 |
|
28 /* |
|
29 Notes: |
|
30 This file defines the DevSound class which acts as an interface to |
|
31 the hardware and is intended to invoke VCR functionality via the plug-ins. |
|
32 The DevSound also contains a product specific policy. |
|
33 */ |
|
34 |
|
35 //UIDs for buffers: According to Symbian: Not used |
|
36 |
|
37 // Public Media Server includes |
|
38 |
|
39 /** |
|
40 @publishedAll |
|
41 @released |
|
42 |
|
43 Sampling rates available. |
|
44 |
|
45 When queried from DevSound by calling the function Capabilities(), iRate indicates |
|
46 the sampling rates supported by the audio device. |
|
47 |
|
48 DevSound by default is configured to 8KHz sampling rate. |
|
49 So to configure DevSound to play/record audio at 16 KHz sampling rate: |
|
50 |
|
51 The mode should not be OR'ed with each other, only single values are accepted. |
|
52 */ |
|
53 enum TMMFSampleRate |
|
54 { |
|
55 /** 8000 Hz Sampling Rate |
|
56 */ |
|
57 EMMFSampleRate8000Hz = 0x00000001, |
|
58 /** 11025 Hz Sampling Rate |
|
59 */ |
|
60 EMMFSampleRate11025Hz = 0x00000002, |
|
61 /** 16000 Hz Sampling Rate |
|
62 */ |
|
63 EMMFSampleRate16000Hz = 0x00000004, |
|
64 /** 22050 Hz Sampling Rate |
|
65 */ |
|
66 EMMFSampleRate22050Hz = 0x00000008, |
|
67 /** 32000 Hz Sampling Rate |
|
68 */ |
|
69 EMMFSampleRate32000Hz = 0x00000010, |
|
70 /** 44100 Hz Sampling Rate |
|
71 */ |
|
72 EMMFSampleRate44100Hz = 0x00000020, |
|
73 /** 48000 Hz Sampling Rate |
|
74 */ |
|
75 EMMFSampleRate48000Hz = 0x00000040, |
|
76 /** 88200 Hz Sampling Rate |
|
77 */ |
|
78 EMMFSampleRate88200Hz = 0x00000080, |
|
79 /** 96000 Hz Sampling Rate |
|
80 */ |
|
81 EMMFSampleRate96000Hz = 0x00000100, |
|
82 /** 12000 Hz Sampling Rate |
|
83 */ |
|
84 EMMFSampleRate12000Hz = 0x00000200, |
|
85 /** 24000 Hz Sampling Rate |
|
86 */ |
|
87 EMMFSampleRate24000Hz = 0x00000400, |
|
88 /** 64000 Hz Sampling Rate |
|
89 */ |
|
90 EMMFSampleRate64000Hz = 0x00000800 |
|
91 }; |
|
92 |
|
93 /** |
|
94 @publishedAll |
|
95 @released |
|
96 |
|
97 Mono Stereo playback and record modes available. |
|
98 |
|
99 When queried from DevSound by calling the function Capabilities(), iChannels |
|
100 indicates whether the underlying audio device supports playing back stereo |
|
101 audio samples and recording audio samples in stereo mode or not. |
|
102 |
|
103 DevSound by default is configured to Mono mode. |
|
104 So to configure DevSound to play/record audio sample in stereo mode: |
|
105 |
|
106 The mode should not be OR'ed with each other, only single values are accepted. |
|
107 */ |
|
108 enum TMMFMonoStereo |
|
109 { |
|
110 /** Mono mode |
|
111 */ |
|
112 EMMFMono = 0x00000001, |
|
113 /** Stereo mode |
|
114 */ |
|
115 EMMFStereo = 0x00000002 |
|
116 }; |
|
117 |
|
118 /** |
|
119 @publishedAll |
|
120 @released |
|
121 |
|
122 Encoding modes available. |
|
123 |
|
124 When queried from DevSound by calling the function Capabilities(), iEncoding |
|
125 provides information about different encoding supported by audio device. |
|
126 |
|
127 DevSound by default is configured to play PCM16 Bit audio data. |
|
128 Setting encoding mode is not supported yet: |
|
129 */ |
|
130 enum TMMFSoundEncoding |
|
131 { |
|
132 /** Signed 8 Bit PCM |
|
133 */ |
|
134 EMMFSoundEncoding8BitPCM = 0x00000001, |
|
135 /** Signed 16 Bit PCM |
|
136 */ |
|
137 EMMFSoundEncoding16BitPCM = 0x00000002, |
|
138 /** Signed 8 Bit ALaw |
|
139 */ |
|
140 EMMFSoundEncoding8BitALaw = 0x00000004, |
|
141 /** Signed 8 Bit MuLaw |
|
142 */ |
|
143 EMMFSoundEncoding8BitMuLaw = 0x00000008, |
|
144 }; |
|
145 |
|
146 /** |
|
147 @publishedAll |
|
148 @released |
|
149 |
|
150 Stereo support enum. |
|
151 */ |
|
152 enum TMMFStereoSupport |
|
153 { |
|
154 /** No stereo support |
|
155 */ |
|
156 EMMFNone = 0x00000000, |
|
157 /** Interleaved stereo support |
|
158 */ |
|
159 EMMFInterleavedOnly = 0x00000001, |
|
160 /** Non Interleaved stereo support |
|
161 */ |
|
162 EMMFNonInterleavedOnly = 0x00000002, |
|
163 /** Interleaved and Non Interleaved stereo support |
|
164 */ |
|
165 EMMFBothNonAndInterleaved = 0x00000003, |
|
166 /** Joint stereo support |
|
167 */ |
|
168 EMMFJoint = 0x00000004 |
|
169 }; |
|
170 |
|
171 /** |
|
172 @publishedAll |
|
173 @released |
|
174 |
|
175 Type class for DevSound implementation device capabilities. |
|
176 |
|
177 CMMFDevSound will return Sampling Rates, Encoding and Stereo feature |
|
178 supported in this structure when queried for capabilities. DevSound can |
|
179 also be configured by setting parameters in this structure and passing the |
|
180 structure to it. |
|
181 */ |
|
182 class TMMFCapabilities |
|
183 { |
|
184 public: |
|
185 /** Sampling Rates supported |
|
186 */ |
|
187 TUint iRate; |
|
188 /** Encodings supported |
|
189 */ |
|
190 TUint iEncoding; |
|
191 /** Mono/Stereo support |
|
192 */ |
|
193 TUint iChannels; |
|
194 /** Buffer size supported |
|
195 */ |
|
196 TInt iBufferSize; |
|
197 }; |
|
198 |
|
199 /** |
|
200 @publishedAll |
|
201 @released |
|
202 |
|
203 An interface to a set of DevSound callback functions. |
|
204 |
|
205 |
|
206 This serves as the method of communication between the client and the |
|
207 DevSound. |
|
208 |
|
209 The class is a mixin and is intended to be inherited by the client class |
|
210 that is interested in observing the DevSound operation. The functions |
|
211 encapsulated by this class are called when specific events occur in the |
|
212 process of initializing and playing/recording an audio sample or playing |
|
213 tones. |
|
214 */ |
|
215 class MDevSoundObserver |
|
216 { |
|
217 public: |
|
218 /** |
|
219 Handles initialization completion event. |
|
220 |
|
221 A derived class must provide an implementation to handle the initialization |
|
222 request. |
|
223 |
|
224 CMMFDevSound object calls this function when its InitializeL() function |
|
225 completes. |
|
226 |
|
227 @param aError |
|
228 Error code. KErrNone if successful. Other values are possible |
|
229 indicating a problem initializing CMMFDevSound object. |
|
230 */ |
|
231 virtual void InitializeComplete(TInt aError)=0; |
|
232 |
|
233 /** |
|
234 Handles tone play completion event. |
|
235 |
|
236 A derived class must provide an implementation to handle the tone play |
|
237 completion request. |
|
238 |
|
239 CMMFDevSound object calls this function when an attempt to play tone has |
|
240 completed, successfully or otherwise. |
|
241 |
|
242 The following are the play tone functions; PlayToneL(), PlayDMTFStringL(), |
|
243 PlayToneSequenceL(), and PlayFixedSequenceL(). |
|
244 |
|
245 @param aError |
|
246 Error code. The status of tone playback. KErrUnderflow playing of |
|
247 the tone is complete. KErrAccessDenied the sound device is in use by |
|
248 another higher priority client. KErrCancel playing of the audio |
|
249 sample is stopped by DevSound client another higher priority client. |
|
250 */ |
|
251 virtual void ToneFinished(TInt aError)=0; |
|
252 |
|
253 /** |
|
254 Handles CMMFDevSound object's data request event. |
|
255 |
|
256 A derived class must provide an implementation to supply CMMFDevSound |
|
257 object the data that it needs to play or convert. |
|
258 |
|
259 CMMFDevSound object calls this function when and where it needs data for |
|
260 playing or converting. The observer should notify CMMFDevSound object as |
|
261 quickly as possible after the data is read into buffer, aBuffer by calling |
|
262 PlayData(), otherwise the implementation might callback function PlayError() |
|
263 on derived class object with error code KErrUnderflow. |
|
264 This does not apply to the very first call to PlayData(), however. |
|
265 It is possible for a user of DevSound to hold the first buffer sent in |
|
266 BufferToBeFilled() until ready to play. |
|
267 The use case for this is if a low latency audio response |
|
268 is required, as at this point all the resources used to play audio are open. |
|
269 If used in this way then it is important to be aware that when when the |
|
270 resources for audio are ready at the BufferToBeFilled() callback, a Devsound |
|
271 on a real device will be running at increased power consumption as the audio |
|
272 hw and any required DSPs will be powered up etc. |
|
273 |
|
274 @param aBuffer |
|
275 Buffer into which data should be read. The amount of data that is |
|
276 needed is specified in CMMFBuffer::RequestSize(). |
|
277 */ |
|
278 virtual void BufferToBeFilled(CMMFBuffer* aBuffer)=0; |
|
279 |
|
280 /** |
|
281 Handles play completion or cancel event. |
|
282 |
|
283 A derived class must provide an implementation to handle the play |
|
284 completion or cancel request. |
|
285 |
|
286 CMMFDevSound object calls this function when an attempt to play audio sample |
|
287 has completed, successfully or otherwise. |
|
288 |
|
289 @param aError |
|
290 Error code. The status of playback. KErrUnderflow playing of the |
|
291 audio sample is complete. KErrAccessDenied the sound device is in |
|
292 use by another higher priority client. |
|
293 */ |
|
294 virtual void PlayError(TInt aError)=0; |
|
295 |
|
296 /** |
|
297 Handles CMMFDevSound object's data request event. |
|
298 |
|
299 A derived class must provide an implementation to process the data |
|
300 supplied by CMMFDevSound object while recording or converting. |
|
301 |
|
302 CMMFDevSound object calls this function when the buffer, aBuffer gets filled |
|
303 while recording or converting. The observer should notify CMMFDevSound |
|
304 object as quickly as possible after data in the buffer is processed by |
|
305 calling RecordData(), otherwise the implementation might callback |
|
306 the function RecordError() on derived class object with error code KErrOverflow. |
|
307 |
|
308 @param aBuffer |
|
309 Buffer containing processed (recorded or converted) data. The amount |
|
310 of data that is available is specified in CMMFBuffer::RequestSize(). |
|
311 */ |
|
312 virtual void BufferToBeEmptied(CMMFBuffer* aBuffer)=0; |
|
313 |
|
314 /** |
|
315 Handles record completion or cancel event. |
|
316 |
|
317 A derived class must provide an implementation to handle the record |
|
318 completion or cancel request. |
|
319 |
|
320 CMMFDevSound object calls this function when an attempt to record audio sample |
|
321 has completed, successfully or otherwise. |
|
322 |
|
323 @param aError |
|
324 Error code. The status of recording. KErrOverflow audio devices |
|
325 runs out of internal buffer. KErrAccessDenied the sound device is |
|
326 in use by another higher priority client. |
|
327 */ |
|
328 virtual void RecordError(TInt aError)=0; |
|
329 |
|
330 /** |
|
331 Handles conversion completion or cancel event. |
|
332 |
|
333 A derived class must provide an implementation to handle the conversion |
|
334 completion or cancel request. |
|
335 |
|
336 CMMFDevSound object calls this function when an attempt to convert data from |
|
337 source format to destination format has completed, successfully or otherwise. |
|
338 |
|
339 @param aError |
|
340 Error code. KErrCancel conversion operation is cancelled. KErrNone |
|
341 conversion is complete. Other values are possible indicating a |
|
342 problem converting data. |
|
343 */ |
|
344 virtual void ConvertError(TInt aError)=0; |
|
345 |
|
346 /** |
|
347 Handles device event. |
|
348 |
|
349 A derived class must provide an implementtion to handle the messages from |
|
350 audio hardware device. |
|
351 |
|
352 CMMFDevSound object calls this function when a message is received from the |
|
353 audio hardware device. |
|
354 |
|
355 @param aMessageType |
|
356 Defines the type of message. Used to determine how to |
|
357 interpret the contents of aMsg. |
|
358 @param aMsg |
|
359 Message that is packed in the Descriptor format. |
|
360 */ |
|
361 virtual void DeviceMessage(TUid aMessageType, const TDesC8& aMsg)=0; |
|
362 |
|
363 |
|
364 /** |
|
365 Handles policy request completion event. |
|
366 |
|
367 A derived class must provide an implementation to handle the policy request |
|
368 completion event. |
|
369 |
|
370 CMMFDevSound object calls this function when an attempt to acquire sound |
|
371 device is rejected by audio policy server. |
|
372 |
|
373 @param aEvent |
|
374 Not used |
|
375 */ |
|
376 inline virtual void SendEventToClient(const TMMFEvent& aEvent); |
|
377 |
|
378 }; |
|
379 |
|
380 |
|
381 /** |
|
382 @publishedAll |
|
383 @released |
|
384 |
|
385 This is the interface from Symbian OS to the raw audio functions on the |
|
386 device hardware. |
|
387 |
|
388 DevSound is currently loaded as a DLL, and implements the VCR-type |
|
389 functions to be expected for such an interface. |
|
390 |
|
391 The audio functions include the following functionality: |
|
392 - Initialisation and configuration of hardware devices, for example, setting microphone gain, |
|
393 setting setero balance and so on. |
|
394 - The playing and recording of raw audio data. |
|
395 - The playing and dynamic control of tones with user specified frequencies. |
|
396 - The playing of DTMF strings. |
|
397 */ |
|
398 class CMMFDevSound : public CBase |
|
399 { |
|
400 public: |
|
401 |
|
402 /** |
|
403 Constructs, and returns a pointer to, a new CMMFDevSound object. |
|
404 |
|
405 Leaves on failure. |
|
406 */ |
|
407 IMPORT_C static CMMFDevSound* NewL(); |
|
408 |
|
409 /** |
|
410 Destructor. |
|
411 |
|
412 Deletes all objects and releases all resource owned by this |
|
413 instance. |
|
414 */ |
|
415 IMPORT_C ~CMMFDevSound(); |
|
416 |
|
417 /** |
|
418 Initializes CMMFDevSound object to play and record PCM16 raw audio data |
|
419 with sampling rate of 8 KHz. |
|
420 |
|
421 On completion of Initialization, calls InitializeComplete() on |
|
422 aDevSoundObserver. |
|
423 |
|
424 Leaves on failure. |
|
425 |
|
426 @param aDevSoundObserver |
|
427 A reference to DevSound Observer instance. |
|
428 @param aMode |
|
429 The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported. |
|
430 |
|
431 |
|
432 */ |
|
433 IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode); |
|
434 |
|
435 |
|
436 /** |
|
437 Initializes DevSound object for the mode aMode for processing audio data |
|
438 with hardware device aHWDev. |
|
439 |
|
440 On completion of Initialization, the observer will be notified via call back |
|
441 InitializeComplete(). |
|
442 |
|
443 Leaves on failure. |
|
444 |
|
445 @param aDevSoundObserver |
|
446 A reference to DevSound Observer instance. |
|
447 @param aHWDev |
|
448 The CMMFHwDevice implementation identifier. |
|
449 @param aMode |
|
450 The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported. |
|
451 |
|
452 */ |
|
453 IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode); |
|
454 |
|
455 /** |
|
456 Initializes DevSound object for the mode aMode for processing audio data |
|
457 with hardware device supporting FourCC aDesiredFourCC. |
|
458 |
|
459 On completion of Initialization, the observer will be notified via call back |
|
460 InitializeComplete(). |
|
461 |
|
462 Leaves on failure. |
|
463 |
|
464 @param aDevSoundObserver |
|
465 A reference to DevSound Observer instance. |
|
466 @param aDesiredFourCC |
|
467 The CMMFHwDevice implementation FourCC code. |
|
468 @param aMode |
|
469 The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported. |
|
470 |
|
471 */ |
|
472 IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode); |
|
473 |
|
474 /** |
|
475 Returns the supported Audio settings ie. encoding, sample rates, mono/stereo operation, buffer |
|
476 size etc. |
|
477 |
|
478 @return The device settings. |
|
479 */ |
|
480 IMPORT_C TMMFCapabilities Capabilities(); |
|
481 |
|
482 /** |
|
483 Returns the current device configuration. |
|
484 |
|
485 @return The device settings. |
|
486 */ |
|
487 IMPORT_C TMMFCapabilities Config() const; |
|
488 |
|
489 /** |
|
490 Configure CMMFDevSound object with the settings in aConfig. |
|
491 |
|
492 Use this to set sampling rate, encoding and mono/stereo. |
|
493 |
|
494 @param aCaps |
|
495 The attribute values to which CMMFDevSound object will be configured to. |
|
496 */ |
|
497 IMPORT_C void SetConfigL(const TMMFCapabilities& aCaps); |
|
498 |
|
499 /** |
|
500 Returns an integer representing the maximum volume device supports. |
|
501 |
|
502 This is the maximum value which can be passed to CMMFDevSound::SetVolume. |
|
503 |
|
504 @return The maximum volume. This value is platform dependent but is always greater than or equal |
|
505 to one. |
|
506 */ |
|
507 IMPORT_C TInt MaxVolume(); |
|
508 |
|
509 /** |
|
510 Returns an integer representing the current volume. |
|
511 |
|
512 @return The current volume level. |
|
513 */ |
|
514 IMPORT_C TInt Volume(); |
|
515 |
|
516 /** |
|
517 Changes the current playback volume to a specified value. |
|
518 |
|
519 The volume can be changed before or during playback and is effective |
|
520 immediately. |
|
521 |
|
522 @param aVolume |
|
523 The volume setting. This can be any value from 0 to the value |
|
524 returned by a call to CMMFDevSound::MaxVolume(). If the |
|
525 volume is not within this range, the volume is automatically set to |
|
526 minimum or maximum value based on the value that is being passed. |
|
527 Setting a zero value mutes the sound. Setting the maximum value |
|
528 results in the loudest possible sound. |
|
529 */ |
|
530 IMPORT_C void SetVolume(TInt aVolume); |
|
531 |
|
532 /** |
|
533 Returns an integer representing the maximum gain the device supports. |
|
534 |
|
535 This is the maximum value which can be passed to CMMFDevSound::SetGain. |
|
536 |
|
537 @return The maximum gain. This value is platform dependent but is always greater than or equal |
|
538 to one. |
|
539 */ |
|
540 IMPORT_C TInt MaxGain(); |
|
541 |
|
542 /** |
|
543 Returns an integer representing the current gain. |
|
544 |
|
545 @return The current gain level. |
|
546 */ |
|
547 IMPORT_C TInt Gain(); |
|
548 |
|
549 /** |
|
550 Changes the current recording gain to a specified value. |
|
551 |
|
552 The gain can be changed before or during recording and is effective |
|
553 immediately. |
|
554 |
|
555 @param aGain |
|
556 The gain setting. This can be any value from zero to the value |
|
557 returned by a call to CMMFDevSound::MaxGain(). If the |
|
558 volume is not within this range, the gain is automatically set to |
|
559 minimum or maximum value based on the value that is being passed. |
|
560 Setting a zero value mutes the sound. Setting the maximum value |
|
561 results in the loudest possible sound. |
|
562 */ |
|
563 IMPORT_C void SetGain(TInt aGain); |
|
564 |
|
565 /** |
|
566 Returns the speaker balance set for playing. |
|
567 |
|
568 Leaves on failure. |
|
569 |
|
570 @param aLeftPercentage |
|
571 On return contains the left speaker volume percentage. |
|
572 @param aRightPercentage |
|
573 On return contains the right speaker volume percentage. |
|
574 */ |
|
575 IMPORT_C void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage); |
|
576 |
|
577 /** |
|
578 Sets the speaker balance for playing. |
|
579 |
|
580 The speaker balance can be changed before or during playback and is |
|
581 effective immediately. |
|
582 |
|
583 @param aLeftPercentage |
|
584 On return contains left speaker volume perecentage. This can be any |
|
585 value from zero to 100. Setting a zero value mutes the sound on left |
|
586 speaker. |
|
587 @param aRightPercentage |
|
588 On return contains right speaker volume perecentage. This can be any |
|
589 value from zero to 100. Setting a zero value mutes the sound on |
|
590 right speaker. |
|
591 */ |
|
592 IMPORT_C void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage); |
|
593 |
|
594 /** |
|
595 Returns the microphone gain balance set for recording. |
|
596 |
|
597 Leaves on failure. |
|
598 |
|
599 @param aLeftPercentage |
|
600 On return contains the left microphone gain percentage. |
|
601 @param aRightPercentage |
|
602 On return contains the right microphone gain percentage. |
|
603 */ |
|
604 IMPORT_C void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage); |
|
605 |
|
606 /** |
|
607 Sets the microphone gain balance for recording. |
|
608 |
|
609 The microphone gain balance can be changed before or during recording and |
|
610 is effective immediately. |
|
611 |
|
612 @param aLeftPercentage |
|
613 The left microphone gain precentage. This can be any value from zero to |
|
614 100. Setting a zero value mutes the gain on left microphone. |
|
615 @param aRightPercentage |
|
616 The right microphone gain precentage. This can be any value from zero to |
|
617 100. Setting a zero value mutes the gain on right microphone. |
|
618 */ |
|
619 IMPORT_C void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage); |
|
620 |
|
621 /** |
|
622 Initializes the audio device and starts the play process. |
|
623 |
|
624 This function queries and acquires the audio policy before initializing audio device. If there was |
|
625 an error during policy initialization, PlayError() function will be called on the observer with |
|
626 error code KErrAccessDenied, otherwise BufferToBeFilled() function will be called with a buffer |
|
627 reference. After reading data into the buffer reference passed, the client should call |
|
628 PlayData() to play data. |
|
629 |
|
630 The amount of data that can be played is specified in |
|
631 CMMFBuffer::RequestSize(). Any data that is read into buffer beyond this |
|
632 size will be ignored. |
|
633 |
|
634 Leaves on failure. |
|
635 |
|
636 @see MDevSoundObserver::PlayError() |
|
637 @see MDevSoundObserver::BufferToBeFilled() |
|
638 */ |
|
639 IMPORT_C void PlayInitL(); |
|
640 |
|
641 /** |
|
642 Initializes audio device and starts the recording process. |
|
643 |
|
644 This function queries and acquires the audio policy before initializing audio device. If there |
|
645 was an error during policy initialization, RecordError() function will be called on the observer |
|
646 with error code KErrAccessDenied, otherwise BufferToBeEmptied() function will be called with a |
|
647 buffer reference. This buffer contains recorded or encoded data. After processing data in the |
|
648 buffer reference passed, the client should call RecordData() to continue recording process. |
|
649 |
|
650 The amount of data that is available is specified in CMMFBuffer::RequestSize(). |
|
651 |
|
652 Leaves on failure. |
|
653 |
|
654 @see MDevSoundObserver::RecordError() |
|
655 @see MDevSoundObserver::BufferToBeEmptied() |
|
656 |
|
657 @capability UserEnvironment |
|
658 For recording - the requesting client process must have the |
|
659 UserEnvironment capability. |
|
660 */ |
|
661 IMPORT_C void RecordInitL(); |
|
662 |
|
663 /** |
|
664 Plays data in the buffer at the current volume. |
|
665 |
|
666 The client should fill the buffer with audio data before calling this function. The observer gets |
|
667 a reference to the buffer along with the callback function BufferToBeFilled(). When playing of |
|
668 the audio sample is complete, successfully or otherwise, the function PlayError() on the |
|
669 observer is called. |
|
670 |
|
671 The last buffer of the audio stream being played should have the last buffer flag set using |
|
672 CMMFBuffer::SetLastBuffer(TBool). If a subsequent attempt to play the clip is made, this flag |
|
673 will need resetting by the client. |
|
674 |
|
675 @see MDevSoundObserver::PlayError() |
|
676 */ |
|
677 IMPORT_C void PlayData(); |
|
678 |
|
679 /** |
|
680 Contine the process of recording. |
|
681 |
|
682 Once the buffer is filled with recorded data, the Observer gets a reference to the buffer along |
|
683 with the callback function BufferToBeEmptied(). After processing the buffer (copying over to a |
|
684 different buffer or writing to file) the client should call this function to continue the |
|
685 recording process. |
|
686 |
|
687 @capability UserEnvironment |
|
688 For recording - the requesting client process must have the |
|
689 UserEnvironment capability. |
|
690 */ |
|
691 IMPORT_C void RecordData(); |
|
692 |
|
693 /** |
|
694 Stops the ongoing operation (Play, Record, TonePlay, Convert). |
|
695 |
|
696 This function should be synchronous and invoke no callbacks through MDevSoundObserver. |
|
697 */ |
|
698 IMPORT_C void Stop(); |
|
699 |
|
700 /** |
|
701 Temporarily Stops the ongoing operation (Play, Record, TonePlay, Convert). |
|
702 |
|
703 The behaviour of Pause() is currently undefined when the initialisation mode |
|
704 is not EMMFStateRecording, consequently different DevSound implementations exhibit |
|
705 different behaviour for pause during play. For this reason, it is recommended that |
|
706 when pausing of audio during playing is required, Stop() is used instead of the call |
|
707 to Pause(). To resume audio playing after Stop(), call PlayInitL(). Among other things, |
|
708 this will internally reset the SamplesPlayed() result and the calling code may need to |
|
709 remember the previous result to give the correct "samples played from start" value. |
|
710 |
|
711 In the case of record, Pause is taken to mean halt any further recording |
|
712 but continue to call the MDevSoundObserver::BufferToBeEmptied() passing |
|
713 already recorded buffers. The last buffer flag should be set when |
|
714 all recorded buffers have been flushed. |
|
715 |
|
716 @see CMMFDevSound::Stop() |
|
717 @see CMMFDevSound::PlayInitL() |
|
718 @see CMMFDevSound::SamplesPlayed() |
|
719 */ |
|
720 IMPORT_C void Pause(); |
|
721 |
|
722 /** |
|
723 Returns the number samples recorded so far. |
|
724 |
|
725 @return The samples recorded. |
|
726 */ |
|
727 IMPORT_C TInt SamplesRecorded(); |
|
728 |
|
729 /** |
|
730 Returns the number of samples played so far. |
|
731 |
|
732 @return The samples played. |
|
733 */ |
|
734 IMPORT_C TInt SamplesPlayed(); |
|
735 |
|
736 /** |
|
737 Initializes the audio device and starts playing a tone. The tone is played with the |
|
738 frequency and duration specified. |
|
739 |
|
740 Leaves on failure. |
|
741 |
|
742 @param aFrequency |
|
743 The frequency at which the tone will be played. |
|
744 @param aDuration |
|
745 The period over which the tone will be played. A zero value causes |
|
746 the no tone to be played. |
|
747 */ |
|
748 IMPORT_C void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration); |
|
749 |
|
750 /** |
|
751 Initializes audio device and starts playing a dual tone. |
|
752 |
|
753 The generated tone consists of two sine waves of different frequencies |
|
754 summed together. |
|
755 |
|
756 Dual Tone is played with the specified frequencies and for the specified duration. |
|
757 |
|
758 @param aFrequencyOne |
|
759 The first frequency of dual tone. |
|
760 @param aFrequencyTwo |
|
761 The second frequency of dual tone |
|
762 @param aDuration |
|
763 The period over which the tone will be played. A zero value causes |
|
764 the no tone to be played (Verify this with test app). |
|
765 */ |
|
766 IMPORT_C void PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration); |
|
767 |
|
768 /** |
|
769 Initializes the audio device and starts playing the DTMF string aDTMFString. |
|
770 |
|
771 Leaves on failure. |
|
772 |
|
773 @param aDTMFString |
|
774 The DTMF sequence in a descriptor. |
|
775 */ |
|
776 IMPORT_C void PlayDTMFStringL(const TDesC& aDTMFString); |
|
777 |
|
778 /** |
|
779 Initializes the audio device and starts playing a tone sequence. |
|
780 |
|
781 Leaves on failure. |
|
782 |
|
783 @param aData |
|
784 The tone sequence in a descriptor. |
|
785 */ |
|
786 IMPORT_C void PlayToneSequenceL(const TDesC8& aData); |
|
787 |
|
788 /** |
|
789 Initializes the audio device and starts playing the specified pre-defined tone |
|
790 sequence. |
|
791 |
|
792 Leaves on failure. |
|
793 |
|
794 @param aSequenceNumber |
|
795 The index identifying the specific pre-defined tone sequence. Index |
|
796 values are relative to zero. |
|
797 This can be any value from zero to the value returned by a call to |
|
798 FixedSequenceCount() - 1. |
|
799 The function raises a panic if the sequence number is not within this |
|
800 range. |
|
801 @see FixedSequenceCount() |
|
802 */ |
|
803 IMPORT_C void PlayFixedSequenceL(TInt aSequenceNumber); |
|
804 |
|
805 /** |
|
806 Defines the number of times the audio is to be repeated during the tone |
|
807 playback operation. |
|
808 |
|
809 A period of silence can follow each playing of a tone. The tone playing can |
|
810 be repeated indefinitely. |
|
811 |
|
812 @param aRepeatCount |
|
813 The number of times the tone, together with the trailing silence, |
|
814 is to be repeated. If this is set to KMdaRepeatForever, then the |
|
815 tone, together with the trailing silence, is repeated indefinitely |
|
816 or until Stop() is called. If this is set to zero, then the tone is |
|
817 not repeated. |
|
818 @param aRepeatTrailingSilence |
|
819 An interval of silence which will be played after each tone. |
|
820 Supported only during tone playing. |
|
821 */ |
|
822 IMPORT_C void SetToneRepeats(TInt aRepeatCount, |
|
823 const TTimeIntervalMicroSeconds& aRepeatTrailingSilence); |
|
824 |
|
825 /** |
|
826 Defines the duration of tone on, tone off and tone pause to be used during the |
|
827 DTMF tone playback operation. |
|
828 |
|
829 Supported only during tone playing. |
|
830 |
|
831 @param aToneOnLength |
|
832 The period over which the tone will be played. If this is set to |
|
833 zero, then the tone is not played. |
|
834 @param aToneOffLength |
|
835 The period over which the no tone will be played. |
|
836 @param aPauseLength |
|
837 The period over which the tone playing will be paused. |
|
838 */ |
|
839 IMPORT_C void SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength, |
|
840 TTimeIntervalMicroSeconds32& aToneOffLength, |
|
841 TTimeIntervalMicroSeconds32& aPauseLength); |
|
842 |
|
843 /** |
|
844 Defines the period over which the volume level is to rise smoothly from |
|
845 nothing to the normal volume level. |
|
846 |
|
847 The function is only available while the tone is playing. |
|
848 |
|
849 @param aRampDuration |
|
850 The period over which the volume is to rise. A zero value causes |
|
851 the tone sample to be played at the normal level for the full |
|
852 duration of the playback. A value, which is longer than the duration |
|
853 of the tone sample means that the sample never reaches its normal |
|
854 volume level. |
|
855 */ |
|
856 IMPORT_C void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration); |
|
857 |
|
858 /** |
|
859 Defines the priority settings that should be used for this instance. |
|
860 |
|
861 @param aPrioritySettings |
|
862 A class type representing the client's priority, priority preference and state. |
|
863 */ |
|
864 IMPORT_C void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings); |
|
865 |
|
866 /** |
|
867 Retrieves a custom interface to the device. |
|
868 |
|
869 @param aInterfaceId |
|
870 The interface UID, defined with the custom interface. |
|
871 |
|
872 @return A pointer to the interface implementation, or NULL if the device does not |
|
873 implement the interface requested. The return value must be cast to the |
|
874 correct type by the user.The user should be careful while caching the custom interface pointer, |
|
875 as in some situations the lower level custom interface pointer may become NULL. |
|
876 */ |
|
877 IMPORT_C TAny* CustomInterface(TUid aInterfaceId); |
|
878 |
|
879 /** |
|
880 Returns the number of available pre-defined tone sequences. |
|
881 |
|
882 This is the number of fixed sequence supported by DevSound by default. |
|
883 |
|
884 @return The fixed sequence count. This value is implementation dependent but is always greater |
|
885 than or equal to zero. |
|
886 */ |
|
887 IMPORT_C TInt FixedSequenceCount(); |
|
888 |
|
889 /** |
|
890 Returns the name assigned to a specific pre-defined tone sequence. |
|
891 |
|
892 This is the number of the fixed sequence supported by DevSound by default. |
|
893 |
|
894 The function raises a panic if sequence number specified is invalid. |
|
895 |
|
896 @param aSequenceNumber |
|
897 The index identifying the specific pre-defined tone sequence. Index values are relative |
|
898 to zero. This can be any value from zero to the value returned by a call to |
|
899 FixedSequenceCount() - 1. |
|
900 The function raises a panic if sequence number is not within this |
|
901 range. |
|
902 |
|
903 @return A reference to a Descriptor containing the fixed sequence name indexed by |
|
904 aSequenceNumber. |
|
905 |
|
906 @see FixedSequenceCount() |
|
907 */ |
|
908 IMPORT_C const TDesC& FixedSequenceName(TInt aSequenceNumber); |
|
909 |
|
910 /** |
|
911 Returns a list of the supported input datatypes that can be sent to DevSound for playing audio. |
|
912 The datatypes returned are those that the DevSound supports given the priority settings passed |
|
913 in aPrioritySettings. |
|
914 |
|
915 Note that if no supported data types are found this does not constitute failure, the function will |
|
916 return normally with no entries in aSupportedDataTypes. |
|
917 |
|
918 @param aSupportedDataTypes |
|
919 The array of supported data types that will be filled in by this function. |
|
920 The supported data types of the DevSound are in the form of an array |
|
921 of TFourCC codes. Any existing entries in the array will be overwritten on |
|
922 calling this function. If no supported data types are found given the priority |
|
923 settings, then the aSupportedDatatypes array will have zero entries. |
|
924 @param aPrioritySettings |
|
925 The priority settings used to determine the supported datatypes. Note this |
|
926 does not set the priority settings. For input datatypes the iState member |
|
927 of the priority settings would be expected to be either |
|
928 EMMFStatePlaying or EMMFStatePlayingRecording. The priority settings may |
|
929 effect the supported datatypes depending on the audio routing. |
|
930 */ |
|
931 IMPORT_C void GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const; |
|
932 |
|
933 /** |
|
934 Returns a list of the supported output dataypes that can be received from DevSound for |
|
935 recording audio. The datatypes returned are those that the DevSound supports given the priority |
|
936 settings passed in aPrioritySettings. |
|
937 |
|
938 Note that if no supported data types are found this does not constitute failure, the function will |
|
939 return normally with no entries in aSupportedDataTypes. |
|
940 |
|
941 @param aSupportedDataTypes |
|
942 The array of supported data types that will be filled in by this function. |
|
943 The supported datatypes of the DevSound are in the form of an array |
|
944 of TFourCC codes. |
|
945 Any existing entries in the array will be overwritten on calling this function. |
|
946 If no supported datatypes are found given the priority settings, then |
|
947 the aSupportedDatatypes array will have zero entries. |
|
948 @param aPrioritySettings |
|
949 The priority settings used to determine the supported data types. Note this |
|
950 does not set the priority settings. For output data types the iState member |
|
951 of the priority settings would expected to be either |
|
952 EMMFStateRecording or EMMFStatePlayingRecording. The priority settings may |
|
953 effect the supported datatypes depending on the audio routing. |
|
954 */ |
|
955 IMPORT_C void GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const; |
|
956 |
|
957 /** |
|
958 Registers the client for notification of resource avalibility. |
|
959 |
|
960 @param aEventType |
|
961 The Notification event type for which the client needs notification. |
|
962 @param aNotificationRegistrationData |
|
963 The Notification Registration data has been reserved for future use and its value should be always NULL |
|
964 @return An error code indicating if the function call was successful. KErrNone on success, |
|
965 KErrNotSupported if the event type is not supported, KErrArgument if the notification data |
|
966 is not null otherwise another of the system-wide error codes. |
|
967 */ |
|
968 inline TInt RegisterAsClient(TUid aEventType, const TDesC8& aNotificationRegistrationData = KNullDesC8); |
|
969 |
|
970 /** |
|
971 Cancels the Registered Notification. |
|
972 |
|
973 @param aEventType |
|
974 The Event type need to cancel |
|
975 @return An error code indicating if the function call was successful. KErrNone on success, KErrNotSupported |
|
976 if the event type is not supported otherwise another of the system-wide error codes. |
|
977 */ |
|
978 inline TInt CancelRegisterAsClient(TUid aEventType); |
|
979 |
|
980 /** |
|
981 Returns the Notification data which the client needs to resume playing. |
|
982 |
|
983 @param aEventType |
|
984 The Event type for which to get notification data |
|
985 @param aNotificationData |
|
986 The reference data for which the client needs to resume the play. The actual data depends on the event type. |
|
987 Note that for the event type 'KMMFEventCategoryAudioResourceAvailable' the package buffer returned |
|
988 is TMMFTimeIntervalMicroSecondsPckg,but the contents should be converted to an integer and |
|
989 interpreted as the data returned is samples played ,but not as a microsecond value. |
|
990 @return An error code indicating if the function call was successful. KErrNone on success, otherwise |
|
991 another of the system-wide error codes. |
|
992 */ |
|
993 inline TInt GetResourceNotificationData(TUid aEventType,TDes8& aNotificationData); |
|
994 |
|
995 /** |
|
996 Wait for the clients to resume play back even after the default timeout expires. |
|
997 Unless the client cancels the notification request or completes no other client gets |
|
998 notification. |
|
999 |
|
1000 @return An error code indicating if the function call was successful. KErrNone on success, |
|
1001 KErrPermissionDenied if the client does not have MultimediaDD capaility, otherwise |
|
1002 another of the system-wide error codes. |
|
1003 */ |
|
1004 inline TInt WillResumePlay(); |
|
1005 |
|
1006 /** |
|
1007 @publishedPartner |
|
1008 @prototype |
|
1009 |
|
1010 Empties the play buffers below DevSound without causing the codec to be deleted. |
|
1011 |
|
1012 @return An error code indicating if the function call was successful. KErrNone on success, |
|
1013 KErrNotSupported if called in a mode other than EMMFStatePlaying or if the function is otherwise not supported, |
|
1014 KErrNotReady if this is called before playing, |
|
1015 otherwise another of the system-wide error codes. |
|
1016 If this function is not supported, it is advised to use Stop(). |
|
1017 */ |
|
1018 inline TInt EmptyBuffers(); |
|
1019 |
|
1020 /** Cancels the initialization process of a CMMFDevSound object |
|
1021 |
|
1022 @return An error code indicating if the function call was successful. |
|
1023 KErrNone on success, |
|
1024 KerrNotReady if this is called before InitializeL() call or after |
|
1025 the object has been initialized, |
|
1026 */ |
|
1027 inline TInt CancelInitialize(); |
|
1028 |
|
1029 /** |
|
1030 Sets client thread info for devsound to make proper policy and routing decisions |
|
1031 |
|
1032 @param aTid |
|
1033 The thread Id of real client. |
|
1034 |
|
1035 @capability MultimediaDD |
|
1036 A process requires MultimediaDD capability to make this call. |
|
1037 */ |
|
1038 inline TInt SetClientThreadInfo(TThreadId aTid); |
|
1039 |
|
1040 /** |
|
1041 Retrieves the current play time from the audio renderer |
|
1042 |
|
1043 @param aTime |
|
1044 A reference to TTimeIntervalMicroSeconds object which will be filled with the current play time by this function. |
|
1045 @return An error code indicating if the function call was successful. |
|
1046 KErrNone on success, |
|
1047 KErrNotSupported if the underlying devsound implementation or the HwDevice does not support this API, |
|
1048 otherwise any of the system-wide error codes. |
|
1049 If this function is not supported, SamplesPlayed() needs to be used instead. |
|
1050 |
|
1051 @see IsGetTimePlayedSupported() |
|
1052 */ |
|
1053 inline TInt GetTimePlayed(TTimeIntervalMicroSeconds& aTime); |
|
1054 |
|
1055 /** |
|
1056 This method can be used by devsound clients to check if the devsound implementation supports |
|
1057 GetTimePlayed API. If this method returns EFalse, SamplesPlayed needs to be used. |
|
1058 |
|
1059 @return ETrue if the underlying devsound implementation supports GetTimePlayed API, |
|
1060 EFalse if the the underlying devsound implementation does not support GetTimePlayed API |
|
1061 |
|
1062 @see GetTimePlayed() |
|
1063 */ |
|
1064 inline TBool IsGetTimePlayedSupported(); |
|
1065 |
|
1066 /** |
|
1067 This method can be used by devsound clients to check if the devsound implementation ignores the underflow |
|
1068 errors from the sound driver and does not propagate them to its clients. |
|
1069 |
|
1070 @return ETrue if devsound ignores all the underflow errors from the sound driver except for the last buffer |
|
1071 That means DevSound propagates the underflow error from sound driver to its clients only when |
|
1072 client sets the last buffer flag on the CMMFBuffer type buffer. |
|
1073 EFalse if devsound propagates the underflow errors from the sound driver in all the cases |
|
1074 |
|
1075 */ |
|
1076 inline TBool QueryIgnoresUnderflow(); |
|
1077 |
|
1078 /** |
|
1079 This method can be used by devsound clients to check if current configuration supports resume |
|
1080 This call is only valid when DevSound is initialized |
|
1081 @return ETrue if current format does supports resume |
|
1082 EFalse otherwise |
|
1083 */ |
|
1084 inline TBool IsResumeSupported(); |
|
1085 |
|
1086 /** |
|
1087 Resume play back, recording or tone playing after this has been paused |
|
1088 @return An error code indicating if the function call was successful. |
|
1089 KErrNone on success, |
|
1090 KErrNotSupported if current format configuration does not support this functionality |
|
1091 KErrNotReady if DevSound is not paused |
|
1092 */ |
|
1093 inline TInt Resume(); |
|
1094 |
|
1095 protected: |
|
1096 |
|
1097 /** |
|
1098 Default Constructor. |
|
1099 */ |
|
1100 //So that nobody can extend derive from CMMFDevSound. |
|
1101 CMMFDevSound(); |
|
1102 |
|
1103 /** |
|
1104 Second phase constructor. |
|
1105 */ |
|
1106 void ConstructL(); |
|
1107 |
|
1108 class CBody; |
|
1109 |
|
1110 /** |
|
1111 DevSound body |
|
1112 */ |
|
1113 CBody* iBody; |
|
1114 }; |
|
1115 |
|
1116 inline void MDevSoundObserver::SendEventToClient(const TMMFEvent& /*aEvent*/) |
|
1117 { |
|
1118 } |
|
1119 |
|
1120 #include <mmf/server/sounddevice.inl> |
|
1121 |
|
1122 #endif // __SOUNDDEVICE_H__ |