1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/d32soundsc.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,620 @@
1.4 +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// e32\include\d32soundsc.h
1.18 +// User side class definition for the shared chunk sound driver.
1.19 +//
1.20 +//
1.21 +
1.22 +/**
1.23 + @file
1.24 + @publishedPartner
1.25 + @prototype
1.26 +*/
1.27 +
1.28 +#ifndef __D32SOUNDSC_H__
1.29 +#define __D32SOUNDSC_H__
1.30 +
1.31 +#include <e32cmn.h>
1.32 +#include <e32ver.h>
1.33 +#ifndef __KERNEL_MODE__
1.34 +#include <e32std.h>
1.35 +#endif
1.36 +
1.37 +_LIT(KDevSoundScName,"SoundSc");
1.38 +
1.39 +const TInt KSoundScTxUnit0=0;
1.40 +const TInt KSoundScTxUnit1=1;
1.41 +/**
1.42 +@capability UserEnvironment
1.43 +@ref RSoundSc::Open An RSoundSc may not be opened for record without UserEnvironment
1.44 +*/
1.45 +const TInt KSoundScRxUnit0=4;
1.46 +/**
1.47 +@capability UserEnvironment
1.48 +@ref RSoundSc::Open An RSoundSc may not be opened for record without UserEnvironment
1.49 +*/
1.50 +const TInt KSoundScRxUnit1=5;
1.51 +
1.52 +// Note that the implementation in the sound driver LDD to calculate a default audio configuration assumes a
1.53 +// monotonic ordering of all caps bitfields. If it is necessary to break this ordering then this implementation
1.54 +// will need to be reviewed and possibly changed.
1.55 +
1.56 +/**
1.57 +Sound driver capability constants - bitmasks of the audio channel configurations supported
1.58 +by a unit. @see TSoundFormatsSupportedV02.
1.59 +*/
1.60 +/** The unit supports Mono (i.e. a single audio channel). */
1.61 +const TUint KSoundMonoChannel = 0x0001;
1.62 +/** The unit supports Stereo (i.e. two audio channels). */
1.63 +const TUint KSoundStereoChannel = 0x0002;
1.64 +/** The unit supports three audio channels. */
1.65 +const TUint KSoundThreeChannel = 0x0004;
1.66 +/** The unit supports four audio channels. */
1.67 +const TUint KSoundFourChannel = 0x0008;
1.68 +/** The unit supports five audio channels. */
1.69 +const TUint KSoundFiveChannel = 0x0010;
1.70 +/** The unit supports six audio channels. */
1.71 +const TUint KSoundSixChannel = 0x0020;
1.72 +
1.73 +/**
1.74 +Sound driver capability constants - bitmasks of supported sample rates. @see TSoundFormatsSupportedV02.
1.75 +*/
1.76 +/** The device supports the 7.35KHz sample rate. */
1.77 +const TUint KSoundRate7350Hz = 0x0001;
1.78 +/** The device supports the 8KHz sample rate. */
1.79 +const TUint KSoundRate8000Hz = 0x0002;
1.80 +/** The device supports the 8.82KHz sample rate. */
1.81 +const TUint KSoundRate8820Hz = 0x0004;
1.82 +/** The device supports the 9.6KHz sample rate. */
1.83 +const TUint KSoundRate9600Hz = 0x0008;
1.84 +/** The device supports the 11.025KHz sample rate. */
1.85 +const TUint KSoundRate11025Hz = 0x0010;
1.86 +/** The device supports the 12KHz sample rate. */
1.87 +const TUint KSoundRate12000Hz = 0x0020;
1.88 +/** The device supports the 14.7KHz sample rate. */
1.89 +const TUint KSoundRate14700Hz = 0x0040;
1.90 +/** The device supports the 16KHz sample rate. */
1.91 +const TUint KSoundRate16000Hz = 0x0080;
1.92 +/** The device supports the 22.05KHz sample rate. */
1.93 +const TUint KSoundRate22050Hz = 0x0100;
1.94 +/** The device supports the 24KHz sample rate. */
1.95 +const TUint KSoundRate24000Hz = 0x0200;
1.96 +/** The device supports the 29.4KHz sample rate. */
1.97 +const TUint KSoundRate29400Hz = 0x0400;
1.98 +/** The device supports the 32KHz sample rate. */
1.99 +const TUint KSoundRate32000Hz = 0x0800;
1.100 +/** The device supports the 44.1KHz sample rate. */
1.101 +const TUint KSoundRate44100Hz = 0x1000;
1.102 +/** The device supports the 48KHz sample rate. */
1.103 +const TUint KSoundRate48000Hz = 0x2000;
1.104 +
1.105 +/**
1.106 +Sound driver capability constants - bitmasks of supported encoding formats. @see TSoundFormatsSupportedV02.
1.107 +*/
1.108 +/** The device supports 8bit PCM encoding format. */
1.109 +const TUint KSoundEncoding8BitPCM = 0x0001;
1.110 +/** The device supports 16bit PCM encoding format. */
1.111 +const TUint KSoundEncoding16BitPCM = 0x0002;
1.112 +/** The device supports 24bit PCM encoding format. */
1.113 +const TUint KSoundEncoding24BitPCM = 0x0004;
1.114 +
1.115 +/**
1.116 +Sound driver capability constants - bitmasks of the data formats supported
1.117 +by the device. @see TSoundFormatsSupportedV02.
1.118 +*/
1.119 +/** The device supports an interleaved data format (i.e. data for each channel is interleaved throughout
1.120 +each data buffer). */
1.121 +const TUint KSoundDataFormatInterleaved = 0x0001;
1.122 +/** The device supports a non-interleaved data format (i.e. data for each channel is arranged in
1.123 +contiguous regions within each data buffer). */
1.124 +const TUint KSoundDataFormatNonInterleaved = 0x0002;
1.125 +
1.126 +/** The maximum setting possible for the record level / volume. */
1.127 +const TInt KSoundMaxVolume = 255;
1.128 +
1.129 +/**
1.130 +Enumeration of possible data transfer directions. @see TSoundFormatsSupportedV02.
1.131 +*/
1.132 +enum TSoundDirection
1.133 + {
1.134 + /** A unit for recording data. */
1.135 + ESoundDirRecord,
1.136 + /** A unit for playing data. */
1.137 + ESoundDirPlayback
1.138 + };
1.139 +
1.140 +/**
1.141 +Enumeration of possible sample rates. @see TCurrentSoundFormatV02.
1.142 +*/
1.143 +enum TSoundRate
1.144 + {
1.145 + /** 7.35KHz sample rate. */
1.146 + ESoundRate7350Hz,
1.147 + /** 8KHz sample rate. */
1.148 + ESoundRate8000Hz,
1.149 + /** 8.82KHz sample rate. */
1.150 + ESoundRate8820Hz,
1.151 + /** 9.6KHz sample rate. */
1.152 + ESoundRate9600Hz,
1.153 + /** 11.025KHz sample rate. */
1.154 + ESoundRate11025Hz,
1.155 + /** 12KHz sample rate. */
1.156 + ESoundRate12000Hz,
1.157 + /** 14.7KHz sample rate. */
1.158 + ESoundRate14700Hz,
1.159 + /** 16KHz sample rate. */
1.160 + ESoundRate16000Hz,
1.161 + /** 22.05KHz sample rate. */
1.162 + ESoundRate22050Hz,
1.163 + /** 24KHz sample rate. */
1.164 + ESoundRate24000Hz,
1.165 + /** 29.4KHz sample rate. */
1.166 + ESoundRate29400Hz,
1.167 + /** 32KHz sample rate. */
1.168 + ESoundRate32000Hz,
1.169 + /** 44.1KHz sample rate. */
1.170 + ESoundRate44100Hz,
1.171 + /** 48KHz sample rate. */
1.172 + ESoundRate48000Hz
1.173 + };
1.174 +
1.175 +/**
1.176 +Enumeration of possible sound encoding formats. @see TCurrentSoundFormatV02.
1.177 +*/
1.178 +enum TSoundEncoding
1.179 + {
1.180 + /** 8bit PCM encoding format. */
1.181 + ESoundEncoding8BitPCM,
1.182 + /** 16bit PCM encoding format. */
1.183 + ESoundEncoding16BitPCM,
1.184 + /** 24bit PCM encoding format. */
1.185 + ESoundEncoding24BitPCM
1.186 + };
1.187 +
1.188 +/**
1.189 +Enumeration of possible sound data formats. @see TCurrentSoundFormatV02.
1.190 +*/
1.191 +enum TSoundDataFormat
1.192 + {
1.193 + /** The device supports an interleaved data format. */
1.194 + ESoundDataFormatInterleaved,
1.195 + /** The device supports a non-interleaved data format. */
1.196 + ESoundDataFormatNonInterleaved
1.197 + };
1.198 +
1.199 +/**
1.200 +The general driver capabilites class - returned by the LDD factory in response to RDevice::GetCaps().
1.201 +*/
1.202 +class TCapsSoundScV01
1.203 + {
1.204 +public:
1.205 + TVersion iVersion;
1.206 + };
1.207 +
1.208 +/**
1.209 +The main audio capabilities class. This is used by the LDD to get either the play or record capabilities
1.210 +of a particular sound device once a channel to it has been opened.
1.211 +*/
1.212 +class TSoundFormatsSupportedV02
1.213 + {
1.214 +public:
1.215 + /** The data transfer direction for this unit: play or record. @see TSoundDirection. */
1.216 + TSoundDirection iDirection;
1.217 + /** The audio channel configurations supported by this unit - a bitfield. */
1.218 + TUint32 iChannels;
1.219 + /** The sample rates supported - a bitfield. */
1.220 + TUint32 iRates;
1.221 + /** The encoding formats supported - a bitfield. */
1.222 + TUint32 iEncodings;
1.223 + /** The data formats supported - a bitfield. */
1.224 + TUint32 iDataFormats;
1.225 + /** The minimum request size that the device can support. All requests to play or record data must be of a
1.226 + length that is a multiple of this value. */
1.227 + TInt iRequestMinSize;
1.228 + /** The logarithm to base 2 of the alignment required for request arguments. All requests to play or
1.229 + record data must specify locations in the shared chunk which conform to this alignment.
1.230 + For example, iRequestAlignment of 1 is 2 byte aligned (2^1), 2 is 4 byte aligned (2^2) etc. */
1.231 + TInt iRequestAlignment;
1.232 + /** Indicates whether this unit is capable of detecting changes in its hardware configuration. */
1.233 + TBool iHwConfigNotificationSupport;
1.234 + /** Reserved field. */
1.235 + TInt iReserved1;
1.236 + };
1.237 +typedef TPckgBuf<TSoundFormatsSupportedV02> TSoundFormatsSupportedV02Buf;
1.238 +
1.239 +/**
1.240 +The sound format configuration class. This is used to get and set the current configuration
1.241 +of the sound device (both for playing and recording).
1.242 +*/
1.243 +class TCurrentSoundFormatV02
1.244 + {
1.245 +public:
1.246 + /** The audio channel configuration: 1=Mono, 2=Stereo etc. */
1.247 + TInt iChannels;
1.248 + /** The sample rate. @see TSoundRate. */
1.249 + TSoundRate iRate;
1.250 + /** The encoding format. @see TSoundEncoding. */
1.251 + TSoundEncoding iEncoding;
1.252 + /** The data format: interleaved, non-interleaved etc. @see TSoundDataFormat. */
1.253 + TSoundDataFormat iDataFormat;
1.254 + /** Reserved field. */
1.255 + TInt iReserved1;
1.256 + };
1.257 +typedef TPckgBuf<TCurrentSoundFormatV02> TCurrentSoundFormatV02Buf;
1.258 +
1.259 +/**
1.260 +A flag that can be passed via the 'aFlags' argument of the function RSoundSc::PlayData(). This being
1.261 +set signifies that this particular play request is the last one of a series (ie EOF) and therefore an underflow is
1.262 +expected after this request completes.
1.263 +*/
1.264 +const TUint KSndFlagLastSample=0x00000001;
1.265 +
1.266 +/** Reserved settings used with CustomConfig(). */
1.267 +const TInt KSndCustomConfigMaxReserved=0x0FFFFFFF;
1.268 +#ifdef _DEBUG
1.269 +const TInt KSndCustom_ForceHwConfigNotifSupported=0x00;
1.270 +const TInt KSndCustom_CompleteChangeOfHwConfig=0x01;
1.271 +const TInt KSndCustom_ForceStartTransferError=0x02;
1.272 +const TInt KSndCustom_ForceTransferDataError=0x03;
1.273 +const TInt KSndCustom_ForceTransferTimeout=0x04;
1.274 +#endif
1.275 +
1.276 +/** A structure used to assemble arguments for the function RSoundSc::PlayData() and to pass these to the driver. */
1.277 +struct SRequestPlayDataInfo
1.278 + {
1.279 + TInt iBufferOffset;
1.280 + TInt iLength;
1.281 + TUint iFlags;
1.282 + };
1.283 +
1.284 +#ifndef __KERNEL_MODE__
1.285 +typedef TPckgBuf<TTimeIntervalMicroSeconds> TTimeIntervalMicroSecondsBuf;
1.286 +#endif
1.287 +
1.288 +class RSoundSc : public RBusLogicalChannel
1.289 + {
1.290 +private:
1.291 + enum TRequest
1.292 + /**
1.293 + Asynchronous request types
1.294 + */
1.295 + {
1.296 + EMsgRequestPlayData,
1.297 + ERequestNotifyChangeOfHwConfig,
1.298 + EMsgRequestMax=3, // All requests less than this value are handled in the driver DFC thread.
1.299 + ERequestRecordData,
1.300 + ENumRequests,
1.301 + EAllRequests = (1<<ENumRequests)-1
1.302 + };
1.303 +
1.304 + enum TControl
1.305 + /**
1.306 + Synchronous request types
1.307 + */
1.308 + {
1.309 + EMsgControlSetAudioFormat,
1.310 + EMsgControlSetBufChunkCreate,
1.311 + EMsgControlSetBufChunkOpen,
1.312 + EMsgControlSetVolume,
1.313 + EMsgControlPause,
1.314 + EMsgControlResume,
1.315 + EMsgControlCancelSpecific,
1.316 + EMsgControlCustomConfig,
1.317 + EControlTimePlayed,
1.318 + EControlTimeRecorded,
1.319 + EMsgControlMax=10, // All requests less than this value are handled in the driver DFC thread.
1.320 + EControlGetCaps,
1.321 + EControlGetAudioFormat,
1.322 + EControlGetBufConfig,
1.323 + EControlGetVolume,
1.324 + EControlBytesTransferred,
1.325 + EControlResetBytesTransferred,
1.326 + EControlReleaseBuffer
1.327 + };
1.328 + friend class DSoundScLdd;
1.329 +public:
1.330 + /**
1.331 + Get the version number of sound driver interface.
1.332 + @return The sound driver interface version number.
1.333 + */
1.334 + inline static TVersion VersionRequired();
1.335 +
1.336 +#ifndef __KERNEL_MODE__
1.337 + /**
1.338 + Open a channel on a specified sound device. This driver allows more than one channel to be opened on each device.
1.339 + @capability MultimediaDD
1.340 + @capability Dependent UserEnvironment Is required when opening a record channel.
1.341 + @param aUnit The unit number of the sound device.
1.342 + @return KErrNone, if successful; KErrPermissionDenied, if process lacks required capabilities
1.343 + otherwise one of the other system-wide error codes.
1.344 + */
1.345 + inline TInt Open(TInt aUnit=KNullUnit);
1.346 +
1.347 + /**
1.348 + Get the capabilities of the sound device.
1.349 + @param aCapsBuf A packaged object which will be filled with the capabilities of the device.
1.350 + @see TSoundFormatsSupportedV02.
1.351 + */
1.352 + inline void Caps(TDes8& aCapsBuf);
1.353 +
1.354 + /**
1.355 + Get the current audio format configuration.
1.356 + @param aFormatBuf A packaged object which will be filled with the audio configuration settings.
1.357 + @see TCurrentSoundFormatV02.
1.358 + */
1.359 + inline void AudioFormat(TDes8& aFormatBuf);
1.360 +
1.361 + /**
1.362 + Set the current audio format configuration.
1.363 + This can't be changed while the driver is currently playing or recording data.
1.364 + @param aFormatBuf A packaged object holding the new audio configuration settings to be used.
1.365 + @return KErrNone if successful;
1.366 + KErrInUse if the playing or recording of data is in progress;
1.367 + KErrNotSupported if any configuration values are invalid;
1.368 + otherwise one of the other system-wide error codes.
1.369 + @see TCurrentSoundFormatV02.
1.370 + */
1.371 + inline TInt SetAudioFormat(const TDesC8& aFormatBuf);
1.372 +
1.373 + /**
1.374 + Get the current buffer configuration.
1.375 + @param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which will be filled with the buffer
1.376 + configuration settings.
1.377 + @see TSharedChunkBufConfigBase.
1.378 + */
1.379 + inline void GetBufferConfig(TDes8& aConfigBuf);
1.380 +
1.381 + /**
1.382 + Set the current buffer configuration - creating a shared chunk.
1.383 + The driver will create a shared chunk according to the buffer specification supplied (and will commit
1.384 + memory to it). This will replace any previous shared chunk created by this driver. A handle to
1.385 + the chunk will then be created for the client thread which will be assigned to the RChunk object supplied
1.386 + by the client.
1.387 + The buffer configuration cannot be changed while the driver is currently playing or recording data.
1.388 + Note that a minimum of three buffers are required when recording: one being loaded with record data by the driver,
1.389 + another also owned by the driver - queued ready for the next transfer and a third owned by the client for processing.
1.390 + Note that for record channels, the buffer size specified effectively determines the size of each record request.
1.391 + Hence, for record channels the buffer size must be a multiple of the minimum request size as specified in the capabilities
1.392 + class. @see TSoundFormatsSupportedV02. It should also be a multiple of the number of bytes per audio sample (e.g. a multiple
1.393 + of 4 for 2 channels of 16bit PCM).
1.394 + @param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which must be set with the new buffer configuration
1.395 + settings to be used. Note that this function will ignore any buffer offset information specified by the
1.396 + caller (i.e. setting the flag KScFlagBufOffsetListInUse has no effect).
1.397 + @param aChunk An RChunk object to which the chunk handle will be assigned.
1.398 + @return KErrNone if successful;
1.399 + KErrInUse if the playing or recording of data is in progress;
1.400 + KErrArgument if any configuration values are invalid;
1.401 + KErrNoMemory if the driver failed to allocate memory for the shared chunk specified;
1.402 + otherwise one of the other system-wide error codes.
1.403 + @see TSharedChunkBufConfigBase.
1.404 + */
1.405 + inline TInt SetBufferChunkCreate(const TDesC8& aConfigBuf,RChunk& aChunk);
1.406 +
1.407 + /**
1.408 + Set the current buffer configuration - using an existing shared chunk.
1.409 + The client supplies an existing shared chunk which is to be used by the driver as the play or record buffer.
1.410 + Any shared chunk previously created by the driver will be closed by it.
1.411 + The buffer configuration cannot be changed while the driver is currently playing or recording data.
1.412 + See RSoundSc::SetBufferChunkCreate for details on the buffer configuration setting necessary for playback or record.
1.413 + @param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which must be set with the buffer configuration
1.414 + settings of the chunk supplied. This must include buffer offset information (i.e. the flag
1.415 + KScFlagBufOffsetListInUse must be set).
1.416 + @param aChunk A handle to the shared chunk which is to be used as the play or record buffer. (This must
1.417 + be a valid handle for the calling thread).
1.418 + @return KErrNone if successful;
1.419 + KErrInUse if the playing or recording of data is in progress;
1.420 + KErrArgument if any configuration values are invalid;
1.421 + otherwise one of the other system-wide error codes.
1.422 + @see TSharedChunkBufConfigBase.
1.423 + */
1.424 + inline TInt SetBufferChunkOpen(const TDesC8& aConfigBuf,RChunk& aChunk);
1.425 +
1.426 + /**
1.427 + Get the current play volume or record level.
1.428 + @return The current play volume / record level - a value in the range 0 to 255. The value 255 equates to
1.429 + the maximum volume and each value below this equates to a 0.5dB step below it.
1.430 + */
1.431 + inline TInt Volume();
1.432 +
1.433 + /**
1.434 + Set the current play volume or record level. The volume can be altered while the driver is in the process
1.435 + of playing or recording data.
1.436 + @param aVolume The play volume / record level to be set - a value in the range 0 to 255. The value 255
1.437 + equates to the maximum volume and each value below this equates to a 0.5dB step below it.
1.438 + @return KErrNone if successful;
1.439 + KErrArgument if the specified volume is out of range;
1.440 + otherwise one of the other system-wide error codes.
1.441 + */
1.442 + inline TInt SetVolume(TInt aVolume);
1.443 +
1.444 + /**
1.445 + Submit a request to play (write data) to the sound device from a buffer.
1.446 + The buffer must be contained within the driver's shared chunk. A single play request may not span more than one
1.447 + buffer even if two or more buffers are contiguous within the shared chunk.
1.448 + The driver will allow more than one play request to be pending at any time. It will
1.449 + process requests in FIFO order. This is an asynchronous operation with the driver completing the request and
1.450 + returning the request status once all the specified data has been delivered to the sound device. The driver
1.451 + will return a request status of KErrUnderflow each time it completes the last pending play request unless this
1.452 + request was marked with the KSndFlagLastSample flag. If this flag is set, the driver will return
1.453 + KErrNone in this situation. Therefore when it is required to play uninterrupted audio by issuing a series of play
1.454 + requests, the client should mark the last play request using this flag.
1.455 + @param aStatus The request status which is signalled when all of the specified data has been transferred to
1.456 + the sound device (or when an error occurs). Possible values:
1.457 + KErrNone: if all the specified data was successfully transferred and no underflow
1.458 + occured following this transfer (or if an underflow occurred but the
1.459 + request was marked with the KSndFlagLastSample flag);
1.460 + KErrUnderflow: if data underflow occurred during or immediately following the transfer;
1.461 + otherwise one of the system-wide error codes.
1.462 + @param aBufferOffset Offset from the beginning of the shared chunk for the start of data to be played. This must be
1.463 + aligned to a value conforming to the iRequestAlignment member of the capabilities structure.
1.464 + @see TSoundFormatsSupportedV02.
1.465 + @param aLength Number of bytes of data to be played. This must be a multiple of the minimum request size as
1.466 + specified in the capabilities class. @see TSoundFormatsSupportedV02. It should also be a multiple
1.467 + of the number of bytes per audio sample (e.g. a multiple of 4 for 2 channels of 16bit PCM).
1.468 + @param aFlags Play request flags. Use KSndFlagLastSample to mark the last play request in a series of play
1.469 + requests.
1.470 + @pre The buffer must have been previously initialised by a call to SetBufferChunkN().
1.471 + */
1.472 + inline void PlayData(TRequestStatus& aStatus,TInt aBufferOffset,TInt aLength,TUint aFlags=0);
1.473 +
1.474 + /**
1.475 + Get the next available record buffer. More than one request may be pending at any time. This is an asynchronous
1.476 + operation. If the driver is not already recording then the issuing of this request will start the capturing of
1.477 + record data from the sound device into a record buffer.
1.478 + @param aStatus The request status which is signalled when buffer is available (or an error occurs). If
1.479 + the request is successful then this result value is set to the offset within the shared chunk
1.480 + where the buffer resides. Alternatively, if an error occurs, it will be set to one of
1.481 + the system wide error values. These include:
1.482 + KErrInUse: if the client needs to free up record buffers;
1.483 + KErrOverflow: if it was necessary for the driver to over-write unread record data since the
1.484 + last record request;
1.485 + KErrCancel: if the device is paused and there is no un-read record data available.
1.486 + otherwise one of the system-wide error codes.
1.487 + @param aLength On return, this contains the number of record bytes successfully stored in the buffer.
1.488 + @pre The record buffer must have been previously initialised by a call to SetBufferChunkN().
1.489 + */
1.490 + inline void RecordData(TRequestStatus& aStatus, TInt& aLength);
1.491 +
1.492 + /**
1.493 + Release a record buffer - making it available again for the driver to record into.
1.494 + @param aChunkOffset: The chunk offset of the image to be released. This is the value that was returned by the
1.495 + RecordData() request when the buffer was claimed by the client.
1.496 + @return KErrNone: if successful;
1.497 + KErrNotFound: if the chunk offset is invalid;
1.498 + otherwise one of the system-wide error codes.
1.499 + */
1.500 + inline TInt ReleaseBuffer(TInt aChunkOffset);
1.501 +
1.502 + /**
1.503 + Cancel all outstanding play requests.
1.504 + This immediately stops the driver playing data and all outstanding play requests are completed with KErrCancel.
1.505 + */
1.506 + inline void CancelPlayData();
1.507 +
1.508 + /**
1.509 + Cancel all outstanding record requests.
1.510 + This immediately stops the driver from capturing record data and all outstanding record requests are completed
1.511 + with KErrCancel.
1.512 + */
1.513 + inline void CancelRecordData();
1.514 +
1.515 + /**
1.516 + Cancel a specific record or play request.
1.517 + The outstanding request completes with KErrCancel.
1.518 + @param aStatus The request status object associated with the request to be cancelled.
1.519 + */
1.520 + inline void Cancel(const TRequestStatus& aStatus);
1.521 +
1.522 + /**
1.523 + For a play back units, this method returns the number of bytes delivered to the sound device hardware. For
1.524 + recording units, this method returns the number of bytes read from the sound device hardware. This is the
1.525 + count since the driver was opened or since the last ResetBytesTransferred() command was issued.
1.526 + @return The number of bytes transferred.
1.527 + @see ResetBytesTransferred()
1.528 + */
1.529 + inline TInt BytesTransferred();
1.530 +
1.531 + /**
1.532 + Reset the count of the number of bytes transferred by the sound device..
1.533 + @see BytesTransferred().
1.534 + */
1.535 + inline void ResetBytesTransferred();
1.536 +
1.537 + /**
1.538 + Halt the playing or recording of data from the sound device.
1.539 + Playing or recording can be resumed using Resume().
1.540 + If an incomplete play request is outstanding when the device is paused, this request does not complete as a
1.541 + result. Resuming play operation following a pause will cause the driver to re-commence playing data from the
1.542 + next sample following the last one played - even of this is part way through a play buffer.
1.543 + However, if an incomplete record request is outstanding when recording is paused, this will be completed immediately
1.544 + as a result. Typically this will be a partially filled record buffer and the number of valid bytes in the buffer are
1.545 + indicated via the length argument of the RecordData() method. The client should release this buffer in the normal
1.546 + way in order to make it available again to the driver when recoding is resumed. Any other outstanding record
1.547 + requests are completed immediately when recording is halted with a return value of KErrCancel. Likewise, record
1.548 + requests received after the device has been paused will complete immediately in the same way - either successfully
1.549 + if un-read data is available or KErrCancel if not. The device must be resumed before it can be primed to capture a
1.550 + new record buffer. The driver will capture no record data while it is in the paused state. If recording is resumed,
1.551 + the driver will begin storing the received data from the beginning of its next available record buffer.
1.552 + @return KErrNone if successful;
1.553 + KErrNotReady: if the driver is not currently playing or recording;
1.554 + otherwise one of the other system-wide error codes.
1.555 + @see Resume()
1.556 + */
1.557 + inline TInt Pause();
1.558 +
1.559 + /**
1.560 + Allow the sound device to resume playing or recording data.
1.561 + This is used resume the operation of the driver following a earlier Pause() command to pause play or record.
1.562 + @return KErrNone if successful;
1.563 + KErrNotReady: if the driver is not currently paused;
1.564 + otherwise one of the other system-wide error codes.
1.565 + @see Pause()
1.566 + */
1.567 + inline TInt Resume();
1.568 +
1.569 + /**
1.570 + Register for notification of a change in the hardware configuration of the device.
1.571 + This is an asynchronous operation. Only one request of this type can be outstanding per driver channel.
1.572 + @param aStatus The request status which is signalled when a change in hardware configuration occurs. Possible
1.573 + values returned:
1.574 + KErrNotSupported: The unit cannot detect changes in configuration;
1.575 + KErrInUse: A notification request is already outstanding for this driver channel.
1.576 + KErrNone: A normal change in hardware configuration has occured;
1.577 + otherwise one of the other system-wide error codes.
1.578 + @param aHeadsetPresent On return, this is set to ETrue if the unit is connected to a microphone or headset socket and
1.579 + this is now present. Otherwise it returns EFalse.
1.580 + */
1.581 + inline void NotifyChangeOfHwConfig(TRequestStatus& aStatus,TBool& aHeadsetPresent);
1.582 +
1.583 + /**
1.584 + Cancel a request for notification of a change in the hardware configuration.
1.585 + This results in a pending request being completed immediately with KErrCancel.
1.586 + */
1.587 + inline void CancelNotifyChangeOfHwConfig();
1.588 +
1.589 + /**
1.590 + Issue a custom configuration request.
1.591 + @param aFunction A number identifying the request. (Values below 0x10000000 are reserved).
1.592 + @param aParam A 32-bit value passed to the driver. Its meaning depends on the request.
1.593 + @return KErrNone if successful, otherwise one of the other system wide error codes.
1.594 + */
1.595 + inline TInt CustomConfig(TInt aFunction,TAny* aParam=NULL);
1.596 +
1.597 + /**
1.598 + Calculates and returns the number of microseconds of data played since the start of playback. If playback ends or
1.599 + if CancelPlayData() is called, this number will be reset.
1.600 + @param aTimePlayed A packaged TTimeIntervalMicroSecondsBuf into which to place the number of microseconds played.
1.601 + @return KErrNone if successful.
1.602 + KErrNotSupported if unit is not open for playback.
1.603 + Otherwise one of the other system wide error codes.
1.604 + */
1.605 + inline TInt TimePlayed(TTimeIntervalMicroSecondsBuf& aTimePlayed);
1.606 +
1.607 + /**
1.608 + Calculates and returns the number of microseconds of data recorded since the start of record. If recording ends or
1.609 + if CancelRecord() is called, this number will be reset.
1.610 + @param aTimeRecorded A packaged TTimeIntervalMicroSecondsBuf into which to place the number of microseconds played.
1.611 + @return KErrNone if successful.
1.612 + KErrNotSupported if unit is not open for recording.
1.613 + Otherwise one of the other system wide error codes.
1.614 + */
1.615 + inline TInt TimeRecorded(TTimeIntervalMicroSecondsBuf& aTimeRecorded);
1.616 +
1.617 +#endif // __KERNEL_MODE__
1.618 + };
1.619 +
1.620 +#include <d32soundsc.inl>
1.621 +
1.622 +#endif // __D32SOUNDSC_H__
1.623 +