typedef int32 (*SoundBufferFunc) ( SoundSpooler *sspl, SoundBufferNode *sbn,int32 msg )
(*UserBufferProcessor)() system. It offers 2 basic improvements over the former: 1. It provides a method of getting buffer start as well as completion notification.
2. UserBufferProcessor can't be called by functions such as ssplDetachInstrument() or ssplPlayData() because these functions do not have a UserBufferProcessor argument. The SoundBufferFunc is stored in the SoundSpooler structure, so all support functions can call it.
The client can install a callback function pointer of this type in the SoundSpooler by calling ssplSetSoundBufferFunc(). Several sound spooler functions send notification messages to this function when the state of a SoundBufferNode changes. When a buffer is started, one of the start class messages is sent to the SoundBufferFunc. When a buffer ends, one of the end class messages is sent.
This callback function is called with a message id, a pointer to the SoundSpooler and SoundBufferNode whose state has changed. The callback function can call non-destructive sound spooler functions like ssplGetUserData(), ssplGetSequencenNum(), etc., but is not permitted to do anything to change the state of the sound spooler. In particular, calling ssplRequestBuffer() or ssplSendBuffer() typically will confuse the sound spooler's list processing functions. Also, the state of SSPL_STATUS_F_ACTIV E is undefined when inside a SoundBufferFunc function.
Generally, the callback function must be able to handle all message types. To simplify message handling, you can get the class of a message by calling ssplGetSBMsgClass(). This is extremely useful if you only care to know that a buffer started or finished, but not the specifics of how it did this.
The callback function is required to return a result. The sound spooler considers a return value >= 0 from the callback function to indicate success. This value does NOT propagate back to the client.
If the callback returns a value <0, that value is returned to the client through the sound spooler function that called the callback function. In this case, the sound spooler function terminates immediately. Any function that can process multiple SoundBufferNodes (e.g. ssplAbort(), or ssplProcessSignals()) doesn't complete its active queue processing when the callback function returns an error code. If the cause of the callback failure can be resolved by the client, the client can usually call the offending function again to continue where it left off.
Use of the SoundBufferFunc and UserBufferProcessor systems are mutually exclusive. When a UserBufferProcessor is supplied to a function that supports it and a SoundBufferFunc is installed, that function fails and returns an error code prior to doing anything.
Start Class
ssplStartSpooler() sends this message for the first buffer in active queue.
ssplProcessSignals() sends this message for the next buffer in the active queue after it removes a completed buffer.
End Class
ssplProcessSignals() sends this mess age for every completed buffer that it removes from the active queue.
ssplAbort() sends this message for ever y buffer (completed or otherwise) that it removes from the active queue.
ssplSetSoundBufferFunc(), ssplGetSBMsgClass(), ssplStartSpooler(), ssplAbort(), ssplProcessSignals(), ssplSendBuffer()