# ssplRequestBuffer

Asks for an available buffer.

### Synopsis

`SoundBufferNode *ssplRequestBuffer ( SoundSpooler *sspl )`

### Description

`ssplRequestBuffer()` returns an available SoundBufferNode from the free queue or NULL if none are available (all are in the active queue). When an available SoundBufferNode is returned, the client can attach sample data to it (by calling `ssplSetBufferAddressLength()`) and submit it to the active queue (by calling `ssplSendBuffer()`). This function is automatically done for you by the convenience functions `ssplSpoolData()` and `ssplPlayData()`.

This function gives you write permission to the returned SoundBufferNode. You have that write permission until the SoundBufferNode is returned to the

SoundSpooler with `ssplSendBuffer()` or `ssplUnrequestBuffer()`.

### Argument

sspl
  Pointer to a SoundSpooler structure.

### Return Value

Pointer to a SoundBufferNode if one is available, or NULL if no buffers are available.

### Implementation

Library call implemented in music.lib V21.

### Examples

The following code fragment shows proper use of ssplRequestBuffer(), ssplUnrequestBuffer(), ssplSetBufferAddressLength(), and ssplSendBuffer().

``

    Err sendbuffer (SoundSpooler *sspl)
    {
        SoundBufferNode *sbn;
        Err errcode;
            // request a buffer
        if ((sbn = ssplRequestBuffer (sspl)) != NULL) {
                // fill buffer, on failure return unused buffer
                // to free queue
            if ((errcode = fillbuffer (sspl, sbn)) < 0) {
                ssplUnrequestBufffer (sspl, sbn);
                return errcode;
            }
                // on success, send buffer (always moves buffer to
                // either free or active queue - no need to unrequest it)
            if ((errcode = ssplSendBuffer (sspl, sbn)) < 0) return
    errcode;
        }
        return 0;
    }
    Err fillbuffer (SoundSpooler *sspl, SoundBufferNode *sbn)
    {
        void *addr;
        uint32 len;
        // your code here to fill buffer - results in addr, len
        return ssplSetBufferAddressLength (sspl, sbn, addr, len);
    }

### Notes

Prior to music.lib V24, SoundBufferNodes were actually _removed_ from the free list; all knowledge of them was lost by the sound spooler until they were passed back to `ssplSendBuffer()` to put them back into one of the SoundSpooler's queues. If lost, `ssplDeleteSoundSpooler()` would lose memory and be unable t o free some items.

Starting with V24, the sound spooler automatically tracks all sound buffer nodes requested by `ssplRequestBuffer()` in a "requested" queue. Any buffers that are not submitted or "unrequested", get put back into the free list by `ssplReset()` and freed by `ssplDeleteSoundSpooler()`.

### Associated Files

soundspooler.h, music.lib

### See Also

``ssplUnrequestBuffer`(), ssplSendBuffer(), ssplSetBufferAddressLength(), ssplSpoolData(), ssplPlayData()`