# SoundBufferFunc

SoundSpooler callback function typedef.

### Synopsis

`typedef int32 (*SoundBufferFunc) ( SoundSpooler *sspl, SoundBufferNode *sbn,int32 msg )`

### Description

This callback system is a superset of the `(*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.

### Arguments

sspl
  SoundSpooler.

sbn
  SoundBufferNode changing state.

msg
  A message id (SSPL_SBMSG_...). See below.

### Messages

`Start Class`

SSPL_SBMSG_INITIAL_START
  Initial Start. `ssplStartSpooler()` sends this message for the first buffer in active queue.

SSPL_SBMSG_LINK_START
  Link Start. `ssplProcessSignals()` sends this message for the next buffer in the active queue after it removes a completed buffer.

SSPL_SBMSG_STARVATION_START

`End Class`

SSPL_SBMSG_COMPLETE
  Complete. `ssplProcessSignals()` sends this mess age for every completed buffer that it removes from the active queue.

SSPL_SBMSG_ABORT
  Abort. `ssplAbort()` sends this message for ever y buffer (completed or otherwise) that it removes from the active queue.

### Return Value

Client should return non-negative value on success, or a negative 3DO error code on failure.

### Implementation

Client-supplied callback function used by music.lib V22.

### Associated Files

soundspooler.h, music.lib

### See Also

``ssplSetSoundBufferFunc`(), ssplGetSBMsgClass(), ssplStartSpooler(), ssplAbort(), ssplProcessSignals(), ssplSendBuffer()`