|
1 // Copyright (c) 1998-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 "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // e32\include\d32soundsc.h |
|
15 // User side class definition for the shared chunk sound driver. |
|
16 // |
|
17 // |
|
18 |
|
19 /** |
|
20 @file |
|
21 @publishedPartner |
|
22 @prototype |
|
23 */ |
|
24 |
|
25 #ifndef __D32SOUNDSC_H__ |
|
26 #define __D32SOUNDSC_H__ |
|
27 |
|
28 #include <e32cmn.h> |
|
29 #include <e32ver.h> |
|
30 #ifndef __KERNEL_MODE__ |
|
31 #include <e32std.h> |
|
32 #endif |
|
33 |
|
34 _LIT(KDevSoundScName,"SoundSc"); |
|
35 |
|
36 const TInt KSoundScTxUnit0=0; |
|
37 const TInt KSoundScTxUnit1=1; |
|
38 /** |
|
39 @capability UserEnvironment |
|
40 @ref RSoundSc::Open An RSoundSc may not be opened for record without UserEnvironment |
|
41 */ |
|
42 const TInt KSoundScRxUnit0=4; |
|
43 /** |
|
44 @capability UserEnvironment |
|
45 @ref RSoundSc::Open An RSoundSc may not be opened for record without UserEnvironment |
|
46 */ |
|
47 const TInt KSoundScRxUnit1=5; |
|
48 |
|
49 // Note that the implementation in the sound driver LDD to calculate a default audio configuration assumes a |
|
50 // monotonic ordering of all caps bitfields. If it is necessary to break this ordering then this implementation |
|
51 // will need to be reviewed and possibly changed. |
|
52 |
|
53 /** |
|
54 Sound driver capability constants - bitmasks of the audio channel configurations supported |
|
55 by a unit. @see TSoundFormatsSupportedV02. |
|
56 */ |
|
57 /** The unit supports Mono (i.e. a single audio channel). */ |
|
58 const TUint KSoundMonoChannel = 0x0001; |
|
59 /** The unit supports Stereo (i.e. two audio channels). */ |
|
60 const TUint KSoundStereoChannel = 0x0002; |
|
61 /** The unit supports three audio channels. */ |
|
62 const TUint KSoundThreeChannel = 0x0004; |
|
63 /** The unit supports four audio channels. */ |
|
64 const TUint KSoundFourChannel = 0x0008; |
|
65 /** The unit supports five audio channels. */ |
|
66 const TUint KSoundFiveChannel = 0x0010; |
|
67 /** The unit supports six audio channels. */ |
|
68 const TUint KSoundSixChannel = 0x0020; |
|
69 |
|
70 /** |
|
71 Sound driver capability constants - bitmasks of supported sample rates. @see TSoundFormatsSupportedV02. |
|
72 */ |
|
73 /** The device supports the 7.35KHz sample rate. */ |
|
74 const TUint KSoundRate7350Hz = 0x0001; |
|
75 /** The device supports the 8KHz sample rate. */ |
|
76 const TUint KSoundRate8000Hz = 0x0002; |
|
77 /** The device supports the 8.82KHz sample rate. */ |
|
78 const TUint KSoundRate8820Hz = 0x0004; |
|
79 /** The device supports the 9.6KHz sample rate. */ |
|
80 const TUint KSoundRate9600Hz = 0x0008; |
|
81 /** The device supports the 11.025KHz sample rate. */ |
|
82 const TUint KSoundRate11025Hz = 0x0010; |
|
83 /** The device supports the 12KHz sample rate. */ |
|
84 const TUint KSoundRate12000Hz = 0x0020; |
|
85 /** The device supports the 14.7KHz sample rate. */ |
|
86 const TUint KSoundRate14700Hz = 0x0040; |
|
87 /** The device supports the 16KHz sample rate. */ |
|
88 const TUint KSoundRate16000Hz = 0x0080; |
|
89 /** The device supports the 22.05KHz sample rate. */ |
|
90 const TUint KSoundRate22050Hz = 0x0100; |
|
91 /** The device supports the 24KHz sample rate. */ |
|
92 const TUint KSoundRate24000Hz = 0x0200; |
|
93 /** The device supports the 29.4KHz sample rate. */ |
|
94 const TUint KSoundRate29400Hz = 0x0400; |
|
95 /** The device supports the 32KHz sample rate. */ |
|
96 const TUint KSoundRate32000Hz = 0x0800; |
|
97 /** The device supports the 44.1KHz sample rate. */ |
|
98 const TUint KSoundRate44100Hz = 0x1000; |
|
99 /** The device supports the 48KHz sample rate. */ |
|
100 const TUint KSoundRate48000Hz = 0x2000; |
|
101 |
|
102 /** |
|
103 Sound driver capability constants - bitmasks of supported encoding formats. @see TSoundFormatsSupportedV02. |
|
104 */ |
|
105 /** The device supports 8bit PCM encoding format. */ |
|
106 const TUint KSoundEncoding8BitPCM = 0x0001; |
|
107 /** The device supports 16bit PCM encoding format. */ |
|
108 const TUint KSoundEncoding16BitPCM = 0x0002; |
|
109 /** The device supports 24bit PCM encoding format. */ |
|
110 const TUint KSoundEncoding24BitPCM = 0x0004; |
|
111 |
|
112 /** |
|
113 Sound driver capability constants - bitmasks of the data formats supported |
|
114 by the device. @see TSoundFormatsSupportedV02. |
|
115 */ |
|
116 /** The device supports an interleaved data format (i.e. data for each channel is interleaved throughout |
|
117 each data buffer). */ |
|
118 const TUint KSoundDataFormatInterleaved = 0x0001; |
|
119 /** The device supports a non-interleaved data format (i.e. data for each channel is arranged in |
|
120 contiguous regions within each data buffer). */ |
|
121 const TUint KSoundDataFormatNonInterleaved = 0x0002; |
|
122 |
|
123 /** The maximum setting possible for the record level / volume. */ |
|
124 const TInt KSoundMaxVolume = 255; |
|
125 |
|
126 /** |
|
127 Enumeration of possible data transfer directions. @see TSoundFormatsSupportedV02. |
|
128 */ |
|
129 enum TSoundDirection |
|
130 { |
|
131 /** A unit for recording data. */ |
|
132 ESoundDirRecord, |
|
133 /** A unit for playing data. */ |
|
134 ESoundDirPlayback |
|
135 }; |
|
136 |
|
137 /** |
|
138 Enumeration of possible sample rates. @see TCurrentSoundFormatV02. |
|
139 */ |
|
140 enum TSoundRate |
|
141 { |
|
142 /** 7.35KHz sample rate. */ |
|
143 ESoundRate7350Hz, |
|
144 /** 8KHz sample rate. */ |
|
145 ESoundRate8000Hz, |
|
146 /** 8.82KHz sample rate. */ |
|
147 ESoundRate8820Hz, |
|
148 /** 9.6KHz sample rate. */ |
|
149 ESoundRate9600Hz, |
|
150 /** 11.025KHz sample rate. */ |
|
151 ESoundRate11025Hz, |
|
152 /** 12KHz sample rate. */ |
|
153 ESoundRate12000Hz, |
|
154 /** 14.7KHz sample rate. */ |
|
155 ESoundRate14700Hz, |
|
156 /** 16KHz sample rate. */ |
|
157 ESoundRate16000Hz, |
|
158 /** 22.05KHz sample rate. */ |
|
159 ESoundRate22050Hz, |
|
160 /** 24KHz sample rate. */ |
|
161 ESoundRate24000Hz, |
|
162 /** 29.4KHz sample rate. */ |
|
163 ESoundRate29400Hz, |
|
164 /** 32KHz sample rate. */ |
|
165 ESoundRate32000Hz, |
|
166 /** 44.1KHz sample rate. */ |
|
167 ESoundRate44100Hz, |
|
168 /** 48KHz sample rate. */ |
|
169 ESoundRate48000Hz |
|
170 }; |
|
171 |
|
172 /** |
|
173 Enumeration of possible sound encoding formats. @see TCurrentSoundFormatV02. |
|
174 */ |
|
175 enum TSoundEncoding |
|
176 { |
|
177 /** 8bit PCM encoding format. */ |
|
178 ESoundEncoding8BitPCM, |
|
179 /** 16bit PCM encoding format. */ |
|
180 ESoundEncoding16BitPCM, |
|
181 /** 24bit PCM encoding format. */ |
|
182 ESoundEncoding24BitPCM |
|
183 }; |
|
184 |
|
185 /** |
|
186 Enumeration of possible sound data formats. @see TCurrentSoundFormatV02. |
|
187 */ |
|
188 enum TSoundDataFormat |
|
189 { |
|
190 /** The device supports an interleaved data format. */ |
|
191 ESoundDataFormatInterleaved, |
|
192 /** The device supports a non-interleaved data format. */ |
|
193 ESoundDataFormatNonInterleaved |
|
194 }; |
|
195 |
|
196 /** |
|
197 The general driver capabilites class - returned by the LDD factory in response to RDevice::GetCaps(). |
|
198 */ |
|
199 class TCapsSoundScV01 |
|
200 { |
|
201 public: |
|
202 TVersion iVersion; |
|
203 }; |
|
204 |
|
205 /** |
|
206 The main audio capabilities class. This is used by the LDD to get either the play or record capabilities |
|
207 of a particular sound device once a channel to it has been opened. |
|
208 */ |
|
209 class TSoundFormatsSupportedV02 |
|
210 { |
|
211 public: |
|
212 /** The data transfer direction for this unit: play or record. @see TSoundDirection. */ |
|
213 TSoundDirection iDirection; |
|
214 /** The audio channel configurations supported by this unit - a bitfield. */ |
|
215 TUint32 iChannels; |
|
216 /** The sample rates supported - a bitfield. */ |
|
217 TUint32 iRates; |
|
218 /** The encoding formats supported - a bitfield. */ |
|
219 TUint32 iEncodings; |
|
220 /** The data formats supported - a bitfield. */ |
|
221 TUint32 iDataFormats; |
|
222 /** The minimum request size that the device can support. All requests to play or record data must be of a |
|
223 length that is a multiple of this value. */ |
|
224 TInt iRequestMinSize; |
|
225 /** The logarithm to base 2 of the alignment required for request arguments. All requests to play or |
|
226 record data must specify locations in the shared chunk which conform to this alignment. |
|
227 For example, iRequestAlignment of 1 is 2 byte aligned (2^1), 2 is 4 byte aligned (2^2) etc. */ |
|
228 TInt iRequestAlignment; |
|
229 /** Indicates whether this unit is capable of detecting changes in its hardware configuration. */ |
|
230 TBool iHwConfigNotificationSupport; |
|
231 /** Reserved field. */ |
|
232 TInt iReserved1; |
|
233 }; |
|
234 typedef TPckgBuf<TSoundFormatsSupportedV02> TSoundFormatsSupportedV02Buf; |
|
235 |
|
236 /** |
|
237 The sound format configuration class. This is used to get and set the current configuration |
|
238 of the sound device (both for playing and recording). |
|
239 */ |
|
240 class TCurrentSoundFormatV02 |
|
241 { |
|
242 public: |
|
243 /** The audio channel configuration: 1=Mono, 2=Stereo etc. */ |
|
244 TInt iChannels; |
|
245 /** The sample rate. @see TSoundRate. */ |
|
246 TSoundRate iRate; |
|
247 /** The encoding format. @see TSoundEncoding. */ |
|
248 TSoundEncoding iEncoding; |
|
249 /** The data format: interleaved, non-interleaved etc. @see TSoundDataFormat. */ |
|
250 TSoundDataFormat iDataFormat; |
|
251 /** Reserved field. */ |
|
252 TInt iReserved1; |
|
253 }; |
|
254 typedef TPckgBuf<TCurrentSoundFormatV02> TCurrentSoundFormatV02Buf; |
|
255 |
|
256 /** |
|
257 A flag that can be passed via the 'aFlags' argument of the function RSoundSc::PlayData(). This being |
|
258 set signifies that this particular play request is the last one of a series (ie EOF) and therefore an underflow is |
|
259 expected after this request completes. |
|
260 */ |
|
261 const TUint KSndFlagLastSample=0x00000001; |
|
262 |
|
263 /** Reserved settings used with CustomConfig(). */ |
|
264 const TInt KSndCustomConfigMaxReserved=0x0FFFFFFF; |
|
265 #ifdef _DEBUG |
|
266 const TInt KSndCustom_ForceHwConfigNotifSupported=0x00; |
|
267 const TInt KSndCustom_CompleteChangeOfHwConfig=0x01; |
|
268 const TInt KSndCustom_ForceStartTransferError=0x02; |
|
269 const TInt KSndCustom_ForceTransferDataError=0x03; |
|
270 const TInt KSndCustom_ForceTransferTimeout=0x04; |
|
271 #endif |
|
272 |
|
273 /** A structure used to assemble arguments for the function RSoundSc::PlayData() and to pass these to the driver. */ |
|
274 struct SRequestPlayDataInfo |
|
275 { |
|
276 TInt iBufferOffset; |
|
277 TInt iLength; |
|
278 TUint iFlags; |
|
279 }; |
|
280 |
|
281 #ifndef __KERNEL_MODE__ |
|
282 typedef TPckgBuf<TTimeIntervalMicroSeconds> TTimeIntervalMicroSecondsBuf; |
|
283 #endif |
|
284 |
|
285 class RSoundSc : public RBusLogicalChannel |
|
286 { |
|
287 private: |
|
288 enum TRequest |
|
289 /** |
|
290 Asynchronous request types |
|
291 */ |
|
292 { |
|
293 EMsgRequestPlayData, |
|
294 ERequestNotifyChangeOfHwConfig, |
|
295 EMsgRequestMax=3, // All requests less than this value are handled in the driver DFC thread. |
|
296 ERequestRecordData, |
|
297 ENumRequests, |
|
298 EAllRequests = (1<<ENumRequests)-1 |
|
299 }; |
|
300 |
|
301 enum TControl |
|
302 /** |
|
303 Synchronous request types |
|
304 */ |
|
305 { |
|
306 EMsgControlSetAudioFormat, |
|
307 EMsgControlSetBufChunkCreate, |
|
308 EMsgControlSetBufChunkOpen, |
|
309 EMsgControlSetVolume, |
|
310 EMsgControlPause, |
|
311 EMsgControlResume, |
|
312 EMsgControlCancelSpecific, |
|
313 EMsgControlCustomConfig, |
|
314 EControlTimePlayed, |
|
315 EControlTimeRecorded, |
|
316 EMsgControlMax=10, // All requests less than this value are handled in the driver DFC thread. |
|
317 EControlGetCaps, |
|
318 EControlGetAudioFormat, |
|
319 EControlGetBufConfig, |
|
320 EControlGetVolume, |
|
321 EControlBytesTransferred, |
|
322 EControlResetBytesTransferred, |
|
323 EControlReleaseBuffer |
|
324 }; |
|
325 friend class DSoundScLdd; |
|
326 public: |
|
327 /** |
|
328 Get the version number of sound driver interface. |
|
329 @return The sound driver interface version number. |
|
330 */ |
|
331 inline static TVersion VersionRequired(); |
|
332 |
|
333 #ifndef __KERNEL_MODE__ |
|
334 /** |
|
335 Open a channel on a specified sound device. This driver allows more than one channel to be opened on each device. |
|
336 @capability MultimediaDD |
|
337 @capability Dependent UserEnvironment Is required when opening a record channel. |
|
338 @param aUnit The unit number of the sound device. |
|
339 @return KErrNone, if successful; KErrPermissionDenied, if process lacks required capabilities |
|
340 otherwise one of the other system-wide error codes. |
|
341 */ |
|
342 inline TInt Open(TInt aUnit=KNullUnit); |
|
343 |
|
344 /** |
|
345 Get the capabilities of the sound device. |
|
346 @param aCapsBuf A packaged object which will be filled with the capabilities of the device. |
|
347 @see TSoundFormatsSupportedV02. |
|
348 */ |
|
349 inline void Caps(TDes8& aCapsBuf); |
|
350 |
|
351 /** |
|
352 Get the current audio format configuration. |
|
353 @param aFormatBuf A packaged object which will be filled with the audio configuration settings. |
|
354 @see TCurrentSoundFormatV02. |
|
355 */ |
|
356 inline void AudioFormat(TDes8& aFormatBuf); |
|
357 |
|
358 /** |
|
359 Set the current audio format configuration. |
|
360 This can't be changed while the driver is currently playing or recording data. |
|
361 @param aFormatBuf A packaged object holding the new audio configuration settings to be used. |
|
362 @return KErrNone if successful; |
|
363 KErrInUse if the playing or recording of data is in progress; |
|
364 KErrNotSupported if any configuration values are invalid; |
|
365 otherwise one of the other system-wide error codes. |
|
366 @see TCurrentSoundFormatV02. |
|
367 */ |
|
368 inline TInt SetAudioFormat(const TDesC8& aFormatBuf); |
|
369 |
|
370 /** |
|
371 Get the current buffer configuration. |
|
372 @param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which will be filled with the buffer |
|
373 configuration settings. |
|
374 @see TSharedChunkBufConfigBase. |
|
375 */ |
|
376 inline void GetBufferConfig(TDes8& aConfigBuf); |
|
377 |
|
378 /** |
|
379 Set the current buffer configuration - creating a shared chunk. |
|
380 The driver will create a shared chunk according to the buffer specification supplied (and will commit |
|
381 memory to it). This will replace any previous shared chunk created by this driver. A handle to |
|
382 the chunk will then be created for the client thread which will be assigned to the RChunk object supplied |
|
383 by the client. |
|
384 The buffer configuration cannot be changed while the driver is currently playing or recording data. |
|
385 Note that a minimum of three buffers are required when recording: one being loaded with record data by the driver, |
|
386 another also owned by the driver - queued ready for the next transfer and a third owned by the client for processing. |
|
387 Note that for record channels, the buffer size specified effectively determines the size of each record request. |
|
388 Hence, for record channels the buffer size must be a multiple of the minimum request size as specified in the capabilities |
|
389 class. @see TSoundFormatsSupportedV02. It should also be a multiple of the number of bytes per audio sample (e.g. a multiple |
|
390 of 4 for 2 channels of 16bit PCM). |
|
391 @param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which must be set with the new buffer configuration |
|
392 settings to be used. Note that this function will ignore any buffer offset information specified by the |
|
393 caller (i.e. setting the flag KScFlagBufOffsetListInUse has no effect). |
|
394 @param aChunk An RChunk object to which the chunk handle will be assigned. |
|
395 @return KErrNone if successful; |
|
396 KErrInUse if the playing or recording of data is in progress; |
|
397 KErrArgument if any configuration values are invalid; |
|
398 KErrNoMemory if the driver failed to allocate memory for the shared chunk specified; |
|
399 otherwise one of the other system-wide error codes. |
|
400 @see TSharedChunkBufConfigBase. |
|
401 */ |
|
402 inline TInt SetBufferChunkCreate(const TDesC8& aConfigBuf,RChunk& aChunk); |
|
403 |
|
404 /** |
|
405 Set the current buffer configuration - using an existing shared chunk. |
|
406 The client supplies an existing shared chunk which is to be used by the driver as the play or record buffer. |
|
407 Any shared chunk previously created by the driver will be closed by it. |
|
408 The buffer configuration cannot be changed while the driver is currently playing or recording data. |
|
409 See RSoundSc::SetBufferChunkCreate for details on the buffer configuration setting necessary for playback or record. |
|
410 @param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which must be set with the buffer configuration |
|
411 settings of the chunk supplied. This must include buffer offset information (i.e. the flag |
|
412 KScFlagBufOffsetListInUse must be set). |
|
413 @param aChunk A handle to the shared chunk which is to be used as the play or record buffer. (This must |
|
414 be a valid handle for the calling thread). |
|
415 @return KErrNone if successful; |
|
416 KErrInUse if the playing or recording of data is in progress; |
|
417 KErrArgument if any configuration values are invalid; |
|
418 otherwise one of the other system-wide error codes. |
|
419 @see TSharedChunkBufConfigBase. |
|
420 */ |
|
421 inline TInt SetBufferChunkOpen(const TDesC8& aConfigBuf,RChunk& aChunk); |
|
422 |
|
423 /** |
|
424 Get the current play volume or record level. |
|
425 @return The current play volume / record level - a value in the range 0 to 255. The value 255 equates to |
|
426 the maximum volume and each value below this equates to a 0.5dB step below it. |
|
427 */ |
|
428 inline TInt Volume(); |
|
429 |
|
430 /** |
|
431 Set the current play volume or record level. The volume can be altered while the driver is in the process |
|
432 of playing or recording data. |
|
433 @param aVolume The play volume / record level to be set - a value in the range 0 to 255. The value 255 |
|
434 equates to the maximum volume and each value below this equates to a 0.5dB step below it. |
|
435 @return KErrNone if successful; |
|
436 KErrArgument if the specified volume is out of range; |
|
437 otherwise one of the other system-wide error codes. |
|
438 */ |
|
439 inline TInt SetVolume(TInt aVolume); |
|
440 |
|
441 /** |
|
442 Submit a request to play (write data) to the sound device from a buffer. |
|
443 The buffer must be contained within the driver's shared chunk. A single play request may not span more than one |
|
444 buffer even if two or more buffers are contiguous within the shared chunk. |
|
445 The driver will allow more than one play request to be pending at any time. It will |
|
446 process requests in FIFO order. This is an asynchronous operation with the driver completing the request and |
|
447 returning the request status once all the specified data has been delivered to the sound device. The driver |
|
448 will return a request status of KErrUnderflow each time it completes the last pending play request unless this |
|
449 request was marked with the KSndFlagLastSample flag. If this flag is set, the driver will return |
|
450 KErrNone in this situation. Therefore when it is required to play uninterrupted audio by issuing a series of play |
|
451 requests, the client should mark the last play request using this flag. |
|
452 @param aStatus The request status which is signalled when all of the specified data has been transferred to |
|
453 the sound device (or when an error occurs). Possible values: |
|
454 KErrNone: if all the specified data was successfully transferred and no underflow |
|
455 occured following this transfer (or if an underflow occurred but the |
|
456 request was marked with the KSndFlagLastSample flag); |
|
457 KErrUnderflow: if data underflow occurred during or immediately following the transfer; |
|
458 otherwise one of the system-wide error codes. |
|
459 @param aBufferOffset Offset from the beginning of the shared chunk for the start of data to be played. This must be |
|
460 aligned to a value conforming to the iRequestAlignment member of the capabilities structure. |
|
461 @see TSoundFormatsSupportedV02. |
|
462 @param aLength Number of bytes of data to be played. This must be a multiple of the minimum request size as |
|
463 specified in the capabilities class. @see TSoundFormatsSupportedV02. It should also be a multiple |
|
464 of the number of bytes per audio sample (e.g. a multiple of 4 for 2 channels of 16bit PCM). |
|
465 @param aFlags Play request flags. Use KSndFlagLastSample to mark the last play request in a series of play |
|
466 requests. |
|
467 @pre The buffer must have been previously initialised by a call to SetBufferChunkN(). |
|
468 */ |
|
469 inline void PlayData(TRequestStatus& aStatus,TInt aBufferOffset,TInt aLength,TUint aFlags=0); |
|
470 |
|
471 /** |
|
472 Get the next available record buffer. More than one request may be pending at any time. This is an asynchronous |
|
473 operation. If the driver is not already recording then the issuing of this request will start the capturing of |
|
474 record data from the sound device into a record buffer. |
|
475 @param aStatus The request status which is signalled when buffer is available (or an error occurs). If |
|
476 the request is successful then this result value is set to the offset within the shared chunk |
|
477 where the buffer resides. Alternatively, if an error occurs, it will be set to one of |
|
478 the system wide error values. These include: |
|
479 KErrInUse: if the client needs to free up record buffers; |
|
480 KErrOverflow: if it was necessary for the driver to over-write unread record data since the |
|
481 last record request; |
|
482 KErrCancel: if the device is paused and there is no un-read record data available. |
|
483 otherwise one of the system-wide error codes. |
|
484 @param aLength On return, this contains the number of record bytes successfully stored in the buffer. |
|
485 @pre The record buffer must have been previously initialised by a call to SetBufferChunkN(). |
|
486 */ |
|
487 inline void RecordData(TRequestStatus& aStatus, TInt& aLength); |
|
488 |
|
489 /** |
|
490 Release a record buffer - making it available again for the driver to record into. |
|
491 @param aChunkOffset: The chunk offset of the image to be released. This is the value that was returned by the |
|
492 RecordData() request when the buffer was claimed by the client. |
|
493 @return KErrNone: if successful; |
|
494 KErrNotFound: if the chunk offset is invalid; |
|
495 otherwise one of the system-wide error codes. |
|
496 */ |
|
497 inline TInt ReleaseBuffer(TInt aChunkOffset); |
|
498 |
|
499 /** |
|
500 Cancel all outstanding play requests. |
|
501 This immediately stops the driver playing data and all outstanding play requests are completed with KErrCancel. |
|
502 */ |
|
503 inline void CancelPlayData(); |
|
504 |
|
505 /** |
|
506 Cancel all outstanding record requests. |
|
507 This immediately stops the driver from capturing record data and all outstanding record requests are completed |
|
508 with KErrCancel. |
|
509 */ |
|
510 inline void CancelRecordData(); |
|
511 |
|
512 /** |
|
513 Cancel a specific record or play request. |
|
514 The outstanding request completes with KErrCancel. |
|
515 @param aStatus The request status object associated with the request to be cancelled. |
|
516 */ |
|
517 inline void Cancel(const TRequestStatus& aStatus); |
|
518 |
|
519 /** |
|
520 For a play back units, this method returns the number of bytes delivered to the sound device hardware. For |
|
521 recording units, this method returns the number of bytes read from the sound device hardware. This is the |
|
522 count since the driver was opened or since the last ResetBytesTransferred() command was issued. |
|
523 @return The number of bytes transferred. |
|
524 @see ResetBytesTransferred() |
|
525 */ |
|
526 inline TInt BytesTransferred(); |
|
527 |
|
528 /** |
|
529 Reset the count of the number of bytes transferred by the sound device.. |
|
530 @see BytesTransferred(). |
|
531 */ |
|
532 inline void ResetBytesTransferred(); |
|
533 |
|
534 /** |
|
535 Halt the playing or recording of data from the sound device. |
|
536 Playing or recording can be resumed using Resume(). |
|
537 If an incomplete play request is outstanding when the device is paused, this request does not complete as a |
|
538 result. Resuming play operation following a pause will cause the driver to re-commence playing data from the |
|
539 next sample following the last one played - even of this is part way through a play buffer. |
|
540 However, if an incomplete record request is outstanding when recording is paused, this will be completed immediately |
|
541 as a result. Typically this will be a partially filled record buffer and the number of valid bytes in the buffer are |
|
542 indicated via the length argument of the RecordData() method. The client should release this buffer in the normal |
|
543 way in order to make it available again to the driver when recoding is resumed. Any other outstanding record |
|
544 requests are completed immediately when recording is halted with a return value of KErrCancel. Likewise, record |
|
545 requests received after the device has been paused will complete immediately in the same way - either successfully |
|
546 if un-read data is available or KErrCancel if not. The device must be resumed before it can be primed to capture a |
|
547 new record buffer. The driver will capture no record data while it is in the paused state. If recording is resumed, |
|
548 the driver will begin storing the received data from the beginning of its next available record buffer. |
|
549 @return KErrNone if successful; |
|
550 KErrNotReady: if the driver is not currently playing or recording; |
|
551 otherwise one of the other system-wide error codes. |
|
552 @see Resume() |
|
553 */ |
|
554 inline TInt Pause(); |
|
555 |
|
556 /** |
|
557 Allow the sound device to resume playing or recording data. |
|
558 This is used resume the operation of the driver following a earlier Pause() command to pause play or record. |
|
559 @return KErrNone if successful; |
|
560 KErrNotReady: if the driver is not currently paused; |
|
561 otherwise one of the other system-wide error codes. |
|
562 @see Pause() |
|
563 */ |
|
564 inline TInt Resume(); |
|
565 |
|
566 /** |
|
567 Register for notification of a change in the hardware configuration of the device. |
|
568 This is an asynchronous operation. Only one request of this type can be outstanding per driver channel. |
|
569 @param aStatus The request status which is signalled when a change in hardware configuration occurs. Possible |
|
570 values returned: |
|
571 KErrNotSupported: The unit cannot detect changes in configuration; |
|
572 KErrInUse: A notification request is already outstanding for this driver channel. |
|
573 KErrNone: A normal change in hardware configuration has occured; |
|
574 otherwise one of the other system-wide error codes. |
|
575 @param aHeadsetPresent On return, this is set to ETrue if the unit is connected to a microphone or headset socket and |
|
576 this is now present. Otherwise it returns EFalse. |
|
577 */ |
|
578 inline void NotifyChangeOfHwConfig(TRequestStatus& aStatus,TBool& aHeadsetPresent); |
|
579 |
|
580 /** |
|
581 Cancel a request for notification of a change in the hardware configuration. |
|
582 This results in a pending request being completed immediately with KErrCancel. |
|
583 */ |
|
584 inline void CancelNotifyChangeOfHwConfig(); |
|
585 |
|
586 /** |
|
587 Issue a custom configuration request. |
|
588 @param aFunction A number identifying the request. (Values below 0x10000000 are reserved). |
|
589 @param aParam A 32-bit value passed to the driver. Its meaning depends on the request. |
|
590 @return KErrNone if successful, otherwise one of the other system wide error codes. |
|
591 */ |
|
592 inline TInt CustomConfig(TInt aFunction,TAny* aParam=NULL); |
|
593 |
|
594 /** |
|
595 Calculates and returns the number of microseconds of data played since the start of playback. If playback ends or |
|
596 if CancelPlayData() is called, this number will be reset. |
|
597 @param aTimePlayed A packaged TTimeIntervalMicroSecondsBuf into which to place the number of microseconds played. |
|
598 @return KErrNone if successful. |
|
599 KErrNotSupported if unit is not open for playback. |
|
600 Otherwise one of the other system wide error codes. |
|
601 */ |
|
602 inline TInt TimePlayed(TTimeIntervalMicroSecondsBuf& aTimePlayed); |
|
603 |
|
604 /** |
|
605 Calculates and returns the number of microseconds of data recorded since the start of record. If recording ends or |
|
606 if CancelRecord() is called, this number will be reset. |
|
607 @param aTimeRecorded A packaged TTimeIntervalMicroSecondsBuf into which to place the number of microseconds played. |
|
608 @return KErrNone if successful. |
|
609 KErrNotSupported if unit is not open for recording. |
|
610 Otherwise one of the other system wide error codes. |
|
611 */ |
|
612 inline TInt TimeRecorded(TTimeIntervalMicroSecondsBuf& aTimeRecorded); |
|
613 |
|
614 #endif // __KERNEL_MODE__ |
|
615 }; |
|
616 |
|
617 #include <d32soundsc.inl> |
|
618 |
|
619 #endif // __D32SOUNDSC_H__ |
|
620 |