Playback +operation

Normal operation

The client calls RSoundSc::PlayData() to +issue an audio request.

The LDD breaks the audio request into manageable +fragments and transfers them to the PDD by calling DSoundScPdd::TransferData().

When +the PDD has transmitted the fragment it calls DSoundScLdd::PlayCallback() to +signal to the LDD that it has finished transfer of a fragment. When the client +request has been completed, the LDD calls DSoundScPdd::StopTransfer() to +stop the PDD transmitting data and to release any transfer specific resources.

To +ensure uninterrupted playback, a client must have multiple play requests pending +on the driver. As soon as one request completes, the client issues a further +request until the end of the track. Typically, a client issues a series of +calls to RSoundSc::PlayData() to play an audio track.

Each RSoundSc::PlayData() request +is handled in the context of the driver's Deferred Function Call (DFC) thread. +Assuming that the driver is not already in the process of playing data when +the first request is received, the LDD checks whether the client has specified +or supplied a shared +chunk to the Driver +channel and also whether the audio configuration and volume have both +been set. If the chunk configuration has not been specified, then the driver +cannot proceed and returns KErrNotReady. However, if the +audio configuration or volume has not been specified, then the LDD simply +applies default settings to the audio hardware device. These values are returned +by the PDD functions DSoundScPdd::SetConfig() and DSoundScPdd::SetVolume() when +called by the LDD.

The LDD may need to break the play request down +into fragments to support the maximum amount of data that the PDD can handle +in a single transfer. The function DSoundScPdd::MaxTransferLen() returns +this maximum value. The LDD queues as many transfer fragments on the PDD as +it can accept with a call to DSoundScPdd::TransferData() for +each fragment.

To support uninterrupted transfer of audio data, the +PDD must be able to accept at least two transfer fragments simultaneously: +the first being actively transferred by the audio hardware device, the other +being queued for transfer on the same device. Therefore, as long as the LDD +has transfer fragments still to queue, it continues to call DSoundScPdd::TransferData() on +the PDD until this signals that it has temporarily reached its capacity, by +returning KErrNotReady.

If the PDD accepts all the +fragments for this initial play request then the LDD moves on to process the +subsequent requests from the client. These are also fragmented until either +the PDD reaches its capacity or all pending play requests are queued.

Each +time the PDD completes the transfer of a fragment from a play buffer, it must +signal this event back to the LDD by calling the function DSoundScLdd::PlayCallback(). +This must always be called in the context of the driver DFC thread so there +are no synchronisation problems. For example, where transfer completion interrupts +the processing of new play requests from the client.

In executing DSoundScLdd::PlayCallback(), +the LDD checks whether the entire transfer for the current request is now +complete. If so, it signals completion back to the client. Also within the DSoundScLdd::PlayCallback() function, +the LDD will attempt to queue further fragments on the PDD, by calling DSoundScPdd::TransferData(), +as the PDD should now have the capability to accept more transfers. The PDD +must be written to handle calls to DSoundScPdd::TransferData() within +its callback to DSoundScLdd::PlayCallBack().

If, +on completing a request from the client, the LDD discovers that there are +no further play requests pending from the client, then this is treated as +an underflow situation and KErrUnderflow is returned to the +client. If however, the client specified KSndFlagLastSample as +the aFlag argument of the RSoundSc::PlayData() function +then an underflow is expected after this request completes.

When the +audio request has been completed the LDD calls DSoundScPdd::StopTransfer() on +the PDD. This allows the PDD to release any resources necessary for transfer.

Pausing and resuming audio playback

The client +may temporarily halt the progress of audio playback at any time by issuing DSoundScLdd::Pause(). +In order to configure the audio hardware device to halt playback, the LDD +calls DSoundScPdd::PauseTransfer() on the PDD. Ideally, +playback should be suspended in such a way that it can be resumed later, starting +from next sample following the one last played.

The client +requests resumption of playback by calling DSoundScLdd::Resume() on +the LDD. The LDD, in turn tells the PDD to re-commence playback by calling DSoundScPdd::ResumeTransfer()

Since +access to the hardware is required in both cases, pause and resume are handled +in the context of the driver DFC thread.

Error handling during playback

If the PDD reports +an error when setting up the audio device for playback then the LDD immediately +completes the first play request back to the client returning the error value +as the result. For example, if the PDD returns a value other than KErrNone from +a call to the function DSoundScPdd::StartTransfer(). The +LDD attempts to re-start playback data transfer when it processes any further +play requests from the client.

If the PDD reports an error when commencing +transfer or as the result of the transfer of a playback fragment, then the +LDD ceases transfer of the associated request and instead immediately completes +the request back to the client returning the error value as the result.

Unexpected +errors from the PDD are returned to the LDD via the functions DSoundScPdd::TransferData() and DSoundScLdd::PlayCallback(). The DSoundScPdd::TransferData() function signals that +an error has occurred when setting up the transfer of a playback fragment +by returning an error value other than KErrNone or KErrNotReady. +The DSoundScLdd::PlayCallback() function called by the +PDD at the end of a transfer, signals an error to the LDD if the value passed +is not equal to KErrNone.

The LDD does not cancel +the transfer of other fragments for the same request which are already queued +on the PDD, but it ignores their outcome. However, the LDD does try to carry +on with the transfer of subsequent play requests queued by the client.

In +any of the above situations, the client may choose to terminate playback operation +by cancelling all outstanding play requests when it detects a playback error.