Adding Sound and Video - Marmalade SDK Mobile Game Development Essentials - page 191

To poll whether an audio track has completed or not, we can do the following:
if (s3eAudioIsPlaying() == S3E_FALSE)
{
// Audio is not playing!
}
This function returns S3E_TRUE if the audio is currently playing, or S3E_FALSE
if it is stopped or paused. This function is actually just a shortcut for calling
s3eAudioGetInt with the property S3E_AUDIO_STATUS .
The callback approach is also very simple to use, as the following code snippet shows:
int32 AudioFinished(s3eAudioCallbackData* apAudioData,
void* apUserData)
{
// apAudioData->m_ChannelID identifies the audio channel that
// has completed.
// s3eCallback functions must return a value, but in case of
// audio callback the value returned does not matter.
return 0;
}
// Use the following line to set up the audio callback
s3eAudioRegister(S3E_AUDIO_STOP, (s3eCallback) AudioFinished, NULL);
// And this line to remove the callback function
s3eAudioUnRegister(S3E_AUDIO_STOP, (s3eCallback) AudioFinished);
The callback function will be called whenever an audio track finishes and will pass
the pointer to user data supplied as the last parameter in the s3eAudioRegister call
by using the apUserData argument. It will not be called if we have asked the audio
track to be looped unless it is the last repetition. The function will also be called if
the audio is stopped due to an error, such as a corrupted track. We can determine
whether completion was caused due to error by calling the s3eAudioGetError
function, which returns an error code of the enumerated type s3eAudioError . A
complete list of error codes can be found in s3eAudio.h .
The decision of whether to use the polling or callback-based approach depends on
your application, and indeed quite often in games we don't even really care that
much about when an audio track has finished as we often just want the same track to
loop forever until a new piece of audio is required. If you are just waiting for a jingle
to finish during a splash screen, the polled method is probably adequate, but if you
want to join several tracks together one after the other, the callback approach would
probably lead to a clean solution.