Unqueueing command
Once a queue entry for a buffer has been append to a queue and is pending processing, it should not be changed. Removal of a given queue entry is not possible unless the Source is STOPPED, in which case then entire queue is considered processed. Removal is possible on a PLAYING or PAUSED Source if the queue entry has already been processed.
The Unqueue command removes a number of buffers entries that have finished processing, in the order of appearance, from the queue. The operation will fail if more buffers are requested than available, leaving the destination arguments unchanged. An INVALID_VALUE error will be thrown. If no error, the destination argument will have been updated accordingly. Loop direction, loop counter, and other attributes queued along with the BUFFER are lost.
void Unqueue ( uint sourceName , sizei numEntries , uint * bufferNames );
 | Annotation (No Retrieval of Loop Attributes) |
|---|---|
The application needs to remove queue entries before it can release buffer names. There is no need to provide query for the other queue entries. |
| Annotation (Unqueueing shared buffers) |
|---|---|
There is an ambiguity in the QUEUED buffer state if a buffer is queued with more than one source, one of which might be finished with it, while the other is not. With the current interface, the application is forced to maintain its own list of consumers (Sources) for a buffer it wishes to unqueue. Future revisions of the API might address this by providing means to explicitely synchronize a Source with another, |
| Annotation (No UNQUEUE token) |
|---|---|
To preserve the distinction between tokens for state query and setting vs. function calls for other commands. |
| Annotation (No Name based access) |
|---|---|
No interface is provided to access a queue entry by name, due to ambiguity (same buffer name scheduled several times in a sequence). |
| Annotation (No Index based access) |
|---|---|
No interface is provided for random access to a queue entry by index. |