ssplProcessSignals

Process completion signals that have been received.

Synopsis

int32 ssplProcessSignals ( SoundSpooler *sspl,int32 SignalMask, void (*UserBufferProcessor) ( SoundSpooler *,SoundBufferNode * ) )

Description

ssplProcessSignals() informs the spooler about which buffers have finished, so the spooler can move them to the free buffer queue.

If a SoundBufferFunc in installed, a SSPL_SBMSG_COMPLETE message is sent to it with each completed SoundBufferNode removed from the active queue. Also, a SSPL_SBMSG_LINK_START message is sent with the next buffer in the active queue. If UserBufferProcessor is non-NULL, each completed SoundBufferNode removed from the active queue is passed to it. If both a SoundBufferFunc and UserBufferProcessor are supplied, ssplProcessSignals() fails and returns ML_ERR_BAD_ARG.

In SoundBufferFunc fails, ssplProcessSignals() fails immediately and returns the error code returned by SoundBufferFunc without processing the rest of the signals. Calling ssplProcessSignals() again with the same signal set picks up where it left off.

Clears SSPL_STATUS_F_ACTIVE when all of the active buffers have completed (i.e. the flag is cleared when this function has processed the completion signals for all of the buffers that were in the active queue at the time that this function was called). You can use this to detect when the last submitted buffer has finished.

Arguments

sspl: Pointer to a SoundSpooler structure.

SignalMask: Signals received from WaitSignal().

UserBufferProcessor: Function for each completed SoundBufferNode, or NULL.

Return Value

Non-negative value on success indicating number of completed buffers removed from the active queue, or negative 3DO error code on failure.

Implementation

Library call implemented in music.lib V21.

Associated Files

soundspooler.h, music.lib

Notes

ssplProcessSignals() synchronizes the sound spooler's queues to the set of signals collected at the last WaitSignal(). Many of the other sound spooler functions assume that the sound spooler has been synchronized in this way (in particular ssplSendBuffer()). Do not call any sound spooler functions between a WaitSignal() involving sound spooler signals and ssplProcessSignals().

Caveats

In the case where SoundBufferFunc(SSPL_SBMSG_COMPLETE) returns an error cod e, SoundBufferFunc(SSPL_SBMSG_LINK_START) isn't called for the next buffer in the active queue, because processing terminates immediately on receipt of the failure of SoundBufferFunc(SSPL_SBMSG_COMPLETE) even when ssplProcessSignals() is called again.