BASS_ChannelRef

Changes the reference count of a stream, MOD music or recording channel. 

BOOL BASS_ChannelRef(
    DWORD handle,
    BOOL inc
);

Parameters

handleThe channel handle... a HMUSIC, HSTREAM or HRECORD.
incIncrement or decrement the reference count... TRUE = increment, FALSE = decrement.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLEhandle is not a valid channel.
BASS_ERROR_ALREADYThe channel already has a 0 reference count so cannot be decremented.
BASS_ERROR_FREEINGThe channel's reference count cannot be incremented because it is being freed.

Remarks

Increasing a channel's reference count prevents it being freed. When BASS_ChannelFree or similar is called to free a channel that does not have a 0 reference count, the channel will be invalidated so that only this function and BASS_ChannelLock can subsequently be called on it; other functions will fail with a BASS_ERROR_FREEING error. The channel will be freed asynchronously (in another thread) once it has a 0 reference count (and it is unlocked).

This can be useful when accessing the channel's memory (eg. tags) to ensure that it is not freed in the meantime by another thread. The reference count can be incremented and decremented by different threads.

Example

Increase a channel's reference count while processing its ID3 tags. 
if (BASS_ChannelRef(channel, true)) { // increment reference count
    const TAG_ID3 *tags = (const TAG_ID3*)BASS_ChannelGetTags(channel, BASS_TAG_ID3); // get the ID3 tags
    // process the tags here
    BASS_ChannelRef(channel, false); // decrement reference count
}

Free a channel asynchronously. 

if (BASS_ChannelRef(channel, true)) { // increment reference count
    BASS_ChannelFree(channel); // invalidate the channel
    BASS_ChannelRef(channel, false); // decrement reference count and free the channel
}

See also

BASS_ChannelFree, BASS_ChannelGetTags, BASS_ChannelLock