RSoundSc Class Reference

class RSoundSc : public RBusLogicalChannel

Inherits from

Public Member Functions
voidAudioFormat(TDes8 &)
TInt BytesTransferred()
voidCancel(const TRequestStatus &)
voidCancelNotifyChangeOfHwConfig()
voidCancelPlayData()
voidCancelRecordData()
voidCaps(TDes8 &)
TInt CustomConfig(TInt, TAny *)
voidGetBufferConfig(TDes8 &)
voidNotifyChangeOfHwConfig(TRequestStatus &, TBool &)
TInt Open(TInt)
TInt Pause()
voidPlayData(TRequestStatus &, TInt, TInt, TUint)
voidRecordData(TRequestStatus &, TInt &)
TInt ReleaseBuffer(TInt)
voidResetBytesTransferred()
TInt Resume()
TInt SetAudioFormat(const TDesC8 &)
TInt SetBufferChunkCreate(const TDesC8 &, RChunk &)
TInt SetBufferChunkOpen(const TDesC8 &, RChunk &)
TInt SetVolume(TInt)
TInt TimePlayed(TTimeIntervalMicroSecondsBuf &)
TInt TimeRecorded(TTimeIntervalMicroSecondsBuf &)
TVersion VersionRequired()
TInt Volume()
Inherited Functions
RBusLogicalChannel::DoCancel(TUint)
RBusLogicalChannel::DoControl(TInt)
RBusLogicalChannel::DoControl(TInt,TAny *)
RBusLogicalChannel::DoControl(TInt,TAny *,TAny *)
RBusLogicalChannel::DoCreate(const TDesC &,const TVersion &,TInt,const TDesC *,const TDesC8 *,TOwnerType,TBool)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &,TAny *)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &,TAny *,TAny *)
RBusLogicalChannel::DoSvControl(TInt)
RBusLogicalChannel::DoSvControl(TInt,TAny *)
RBusLogicalChannel::DoSvControl(TInt,TAny *,TAny *)
RBusLogicalChannel::Open(RMessagePtr2,TInt,TOwnerType)
RBusLogicalChannel::Open(TInt,TOwnerType)
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::Close()
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RHandleBase::SetReturnedHandle(TInt)
RHandleBase::SetReturnedHandle(TInt,RHandleBase &)
Private Member Enumerations
enumTControl {
EMsgControlSetAudioFormat, EMsgControlSetBufChunkCreate, EMsgControlSetBufChunkOpen, EMsgControlSetVolume, EMsgControlPause, EMsgControlResume, EMsgControlCancelSpecific, EMsgControlCustomConfig, EControlTimePlayed, EControlTimeRecorded, EMsgControlMax = 10, EControlGetCaps, EControlGetAudioFormat, EControlGetBufConfig, EControlGetVolume, EControlBytesTransferred, EControlResetBytesTransferred, EControlReleaseBuffer
}
enumTRequest {
EMsgRequestPlayData, ERequestNotifyChangeOfHwConfig, EMsgRequestMax = 3, ERequestRecordData, ENumRequests, EAllRequests = (1<<ENumRequests)-1
}
Inherited Enumerations
RHandleBase:TAttributes
Inherited Attributes
RHandleBase::iHandle

Member Functions Documentation

AudioFormat(TDes8 &)

voidAudioFormat(TDes8 &aFormatBuf)[inline]

Get the current audio format configuration. TCurrentSoundFormatV02.

Parameters

TDes8 & aFormatBufA packaged object which will be filled with the audio configuration settings.

BytesTransferred()

TInt BytesTransferred()[inline]

For a play back units, this method returns the number of bytes delivered to the sound device hardware. For recording units, this method returns the number of bytes read from the sound device hardware. This is the count since the driver was opened or since the last ResetBytesTransferred() command was issued. ResetBytesTransferred()

Cancel(const TRequestStatus &)

voidCancel(const TRequestStatus &aStatus)[inline]

Cancel a specific record or play request. The outstanding request completes with KErrCancel.

Parameters

const TRequestStatus & aStatusThe request status object associated with the request to be cancelled.

CancelNotifyChangeOfHwConfig()

voidCancelNotifyChangeOfHwConfig()[inline]

Cancel a request for notification of a change in the hardware configuration. This results in a pending request being completed immediately with KErrCancel.

CancelPlayData()

voidCancelPlayData()[inline]

Cancel all outstanding play requests. This immediately stops the driver playing data and all outstanding play requests are completed with KErrCancel.

CancelRecordData()

voidCancelRecordData()[inline]

Cancel all outstanding record requests. This immediately stops the driver from capturing record data and all outstanding record requests are completed with KErrCancel.

Caps(TDes8 &)

voidCaps(TDes8 &aCapsBuf)[inline]

Get the capabilities of the sound device. TSoundFormatsSupportedV02.

Parameters

TDes8 & aCapsBufA packaged object which will be filled with the capabilities of the device.

CustomConfig(TInt, TAny *)

TInt CustomConfig(TIntaFunction,
TAny *aParam = NULL
)[inline]

Issue a custom configuration request.

Parameters

TInt aFunctionA number identifying the request. (Values below 0x10000000 are reserved).
TAny * aParam = NULLA 32-bit value passed to the driver. Its meaning depends on the request.

GetBufferConfig(TDes8 &)

voidGetBufferConfig(TDes8 &aConfigBuf)[inline]

Get the current buffer configuration. TSharedChunkBufConfigBase.

Parameters

TDes8 & aConfigBufA packaged TSharedChunkBufConfigBase derived object which will be filled with the buffer configuration settings.

NotifyChangeOfHwConfig(TRequestStatus &, TBool &)

voidNotifyChangeOfHwConfig(TRequestStatus &aStatus,
TBool &aHeadsetPresent
)[inline]

Register for notification of a change in the hardware configuration of the device. This is an asynchronous operation. Only one request of this type can be outstanding per driver channel.

Parameters

TRequestStatus & aStatusThe request status which is signalled when a change in hardware configuration occurs. Possible values returned: KErrNotSupported: The unit cannot detect changes in configuration; KErrInUse: A notification request is already outstanding for this driver channel. KErrNone: A normal change in hardware configuration has occured; otherwise one of the other system-wide error codes.
TBool & aHeadsetPresentOn return, this is set to ETrue if the unit is connected to a microphone or headset socket and this is now present. Otherwise it returns EFalse.

Open(TInt)

TInt Open(TIntaUnit =  KNullUnit )[inline]
Open a channel on a specified sound device. This driver allows more than one channel to be opened on each device.
capability
MultimediaDD
capability
Dependent UserEnvironment Is required when opening a record channel.

Parameters

TInt aUnit =  KNullUnit The unit number of the sound device.

Pause()

TInt Pause()[inline]

Halt the playing or recording of data from the sound device. Playing or recording can be resumed using Resume(). If an incomplete play request is outstanding when the device is paused, this request does not complete as a result. Resuming play operation following a pause will cause the driver to re-commence playing data from the next sample following the last one played - even of this is part way through a play buffer. However, if an incomplete record request is outstanding when recording is paused, this will be completed immediately as a result. Typically this will be a partially filled record buffer and the number of valid bytes in the buffer are indicated via the length argument of the RecordData() method. The client should release this buffer in the normal way in order to make it available again to the driver when recoding is resumed. Any other outstanding record requests are completed immediately when recording is halted with a return value of KErrCancel. Likewise, record requests received after the device has been paused will complete immediately in the same way - either successfully if un-read data is available or KErrCancel if not. The device must be resumed before it can be primed to capture a new record buffer. The driver will capture no record data while it is in the paused state. If recording is resumed, the driver will begin storing the received data from the beginning of its next available record buffer. Resume()

PlayData(TRequestStatus &, TInt, TInt, TUint)

voidPlayData(TRequestStatus &aStatus,
TIntaBufferOffset,
TIntaLength,
TUintaFlags = 0
)[inline]
Submit a request to play (write data) to the sound device from a buffer. The buffer must be contained within the driver's shared chunk. A single play request may not span more than one buffer even if two or more buffers are contiguous within the shared chunk. The driver will allow more than one play request to be pending at any time. It will process requests in FIFO order. This is an asynchronous operation with the driver completing the request and returning the request status once all the specified data has been delivered to the sound device. The driver will return a request status of KErrUnderflow each time it completes the last pending play request unless this request was marked with the KSndFlagLastSample flag. If this flag is set, the driver will return KErrNone in this situation. Therefore when it is required to play uninterrupted audio by issuing a series of play requests, the client should mark the last play request using this flag. TSoundFormatsSupportedV02. TSoundFormatsSupportedV02. It should also be a multiple of the number of bytes per audio sample (e.g. a multiple of 4 for 2 channels of 16bit PCM).
Pre-condition
The buffer must have been previously initialised by a call to SetBufferChunkN().

Parameters

TRequestStatus & aStatusThe request status which is signalled when all of the specified data has been transferred to the sound device (or when an error occurs). Possible values: KErrNone: if all the specified data was successfully transferred and no underflow occured following this transfer (or if an underflow occurred but the request was marked with the KSndFlagLastSample flag); KErrUnderflow: if data underflow occurred during or immediately following the transfer; otherwise one of the system-wide error codes.
TInt aBufferOffsetOffset from the beginning of the shared chunk for the start of data to be played. This must be aligned to a value conforming to the iRequestAlignment member of the capabilities structure.
TInt aLengthNumber of bytes of data to be played. This must be a multiple of the minimum request size as specified in the capabilities class.
TUint aFlags = 0Play request flags. Use KSndFlagLastSample to mark the last play request in a series of play requests.

RecordData(TRequestStatus &, TInt &)

voidRecordData(TRequestStatus &aStatus,
TInt &aLength
)[inline]
Get the next available record buffer. More than one request may be pending at any time. This is an asynchronous operation. If the driver is not already recording then the issuing of this request will start the capturing of record data from the sound device into a record buffer.
Pre-condition
The record buffer must have been previously initialised by a call to SetBufferChunkN().

Parameters

TRequestStatus & aStatusThe request status which is signalled when buffer is available (or an error occurs). If the request is successful then this result value is set to the offset within the shared chunk where the buffer resides. Alternatively, if an error occurs, it will be set to one of the system wide error values. These include: KErrInUse: if the client needs to free up record buffers; KErrOverflow: if it was necessary for the driver to over-write unread record data since the last record request; KErrCancel: if the device is paused and there is no un-read record data available. otherwise one of the system-wide error codes.
TInt & aLengthOn return, this contains the number of record bytes successfully stored in the buffer.

ReleaseBuffer(TInt)

TInt ReleaseBuffer(TIntaChunkOffset)[inline]

Release a record buffer - making it available again for the driver to record into.

Parameters

TInt aChunkOffset

ResetBytesTransferred()

voidResetBytesTransferred()[inline]

Reset the count of the number of bytes transferred by the sound device.. BytesTransferred().

Resume()

TInt Resume()[inline]

Allow the sound device to resume playing or recording data. This is used resume the operation of the driver following a earlier Pause() command to pause play or record. Pause()

SetAudioFormat(const TDesC8 &)

TInt SetAudioFormat(const TDesC8 &aFormatBuf)[inline]

Set the current audio format configuration. This can't be changed while the driver is currently playing or recording data. TCurrentSoundFormatV02.

Parameters

const TDesC8 & aFormatBufA packaged object holding the new audio configuration settings to be used.

SetBufferChunkCreate(const TDesC8 &, RChunk &)

TInt SetBufferChunkCreate(const TDesC8 &aConfigBuf,
RChunk &aChunk
)[inline]

Set the current buffer configuration - creating a shared chunk. The driver will create a shared chunk according to the buffer specification supplied (and will commit memory to it). This will replace any previous shared chunk created by this driver. A handle to the chunk will then be created for the client thread which will be assigned to the RChunk object supplied by the client. The buffer configuration cannot be changed while the driver is currently playing or recording data. Note that a minimum of three buffers are required when recording: one being loaded with record data by the driver, another also owned by the driver - queued ready for the next transfer and a third owned by the client for processing. Note that for record channels, the buffer size specified effectively determines the size of each record request. Hence, for record channels the buffer size must be a multiple of the minimum request size as specified in the capabilities class. TSoundFormatsSupportedV02. It should also be a multiple of the number of bytes per audio sample (e.g. a multiple of 4 for 2 channels of 16bit PCM). TSharedChunkBufConfigBase.

Parameters

const TDesC8 & aConfigBufA packaged TSharedChunkBufConfigBase derived object which must be set with the new buffer configuration settings to be used. Note that this function will ignore any buffer offset information specified by the caller (i.e. setting the flag KScFlagBufOffsetListInUse has no effect).
RChunk & aChunkAn RChunk object to which the chunk handle will be assigned.

SetBufferChunkOpen(const TDesC8 &, RChunk &)

TInt SetBufferChunkOpen(const TDesC8 &aConfigBuf,
RChunk &aChunk
)[inline]

Set the current buffer configuration - using an existing shared chunk. The client supplies an existing shared chunk which is to be used by the driver as the play or record buffer. Any shared chunk previously created by the driver will be closed by it. The buffer configuration cannot be changed while the driver is currently playing or recording data. See RSoundSc::SetBufferChunkCreate for details on the buffer configuration setting necessary for playback or record. TSharedChunkBufConfigBase.

Parameters

const TDesC8 & aConfigBufA packaged TSharedChunkBufConfigBase derived object which must be set with the buffer configuration settings of the chunk supplied. This must include buffer offset information (i.e. the flag KScFlagBufOffsetListInUse must be set).
RChunk & aChunkA handle to the shared chunk which is to be used as the play or record buffer. (This must be a valid handle for the calling thread).

SetVolume(TInt)

TInt SetVolume(TIntaVolume)[inline]

Set the current play volume or record level. The volume can be altered while the driver is in the process of playing or recording data.

Parameters

TInt aVolumeThe play volume / record level to be set - a value in the range 0 to 255. The value 255 equates to the maximum volume and each value below this equates to a 0.5dB step below it.

TimePlayed(TTimeIntervalMicroSecondsBuf &)

TInt TimePlayed(TTimeIntervalMicroSecondsBuf &aTimePlayed)[inline]

Calculates and returns the number of microseconds of data played since the start of playback. If playback ends or if CancelPlayData() is called, this number will be reset.

Parameters

TTimeIntervalMicroSecondsBuf & aTimePlayedA packaged TTimeIntervalMicroSecondsBuf into which to place the number of microseconds played.

TimeRecorded(TTimeIntervalMicroSecondsBuf &)

TInt TimeRecorded(TTimeIntervalMicroSecondsBuf &aTimeRecorded)[inline]

Calculates and returns the number of microseconds of data recorded since the start of record. If recording ends or if CancelRecord() is called, this number will be reset.

Parameters

TTimeIntervalMicroSecondsBuf & aTimeRecordedA packaged TTimeIntervalMicroSecondsBuf into which to place the number of microseconds played.

VersionRequired()

TVersion VersionRequired()[static, inline]

Get the version number of sound driver interface.

Volume()

TInt Volume()[inline]

Get the current play volume or record level.

Member Enumerations Documentation

Enum TControl

Synchronous request types

Enumerators

EMsgControlSetAudioFormat
EMsgControlSetBufChunkCreate
EMsgControlSetBufChunkOpen
EMsgControlSetVolume
EMsgControlPause
EMsgControlResume
EMsgControlCancelSpecific
EMsgControlCustomConfig
EControlTimePlayed
EControlTimeRecorded
EMsgControlMax = 10
EControlGetCaps
EControlGetAudioFormat
EControlGetBufConfig
EControlGetVolume
EControlBytesTransferred
EControlResetBytesTransferred
EControlReleaseBuffer

Enum TRequest

Asynchronous request types

Enumerators

EMsgRequestPlayData
ERequestNotifyChangeOfHwConfig
EMsgRequestMax = 3
ERequestRecordData
ENumRequests
EAllRequests = (1<<ENumRequests)-1