Miles Sound System SDK 7.2a

AIL_allocate_sequence_handle

The function AIL_allocate_sequence_handle searches for a free sequence handle and returns it to the application for use in the playback of XMIDI audio data.

HSEQUENCE AIL_allocate_sequence_handle(
  HMDIDRIVER mdi
);

In Parameters

mdi: specifies which XMIDI music driver is to play the sequence data associated with the sample handle.

Returns

A handle to an available sequence slot, or NULL if all sequence handles have already been allocated.

Discussion

Each XMIDI driver, when installed, is provided with a number of sequence handles. Sequence handles are reusable descriptors for application audio data at any moment in time, each instance of a playing XMIDI sequence must be associated with a sequence handle. The number of sequence handles allocated, hence the maximum number of HSEQUENCE sequence handles available from AIL_allocate_sequence_handle, is determined by the MDI_SEQUENCES preference. This value is normally 8, but can be set to any value by use of the AIL_set_preference function prior to driver installation.

After loading a digital audio driver, the application should allocate as many sequence handles as it will require, based on the maximum number of simultaneous XMIDI sequences needed. When an XMIDI sequence is to be played, the application calls AIL_sequence_status for each of its allocated sequence handles, searching for one with the status SEQ_DONE. This indicates that the system is either finished playing the last sequence assigned to the sequence handle, or that the sequence handle has been allocated but not yet used to play a sequence. Assuming an available sequence handle is found, the next step is to call AIL_init_sequence to prepare the sequence handle for use with a new XMIDI sequence, followed by calls to set the playback volume or other playback information as desired. Playback of the sequence will begin when AIL_start_sequence is called.

Upon termination of the application program, it is not necessary to return allocated sequence handles to the MSS system with AIL_release_sequence_handle calls.

Example files that use this function: XMIPLAY.C

Group: XMIDI Services
Related Functions: AIL_allocate_sequence_handle, AIL_end_sequence, AIL_init_sequence, AIL_release_sequence_handle, AIL_sequence_status, AIL_set_preference, AIL_start_sequence, AIL_stop_sequence
Related Basic Types: HMDIDRIVER, HSEQUENCE, MILES_PREFERENCES, MILES_SEQUENCE_STATUS
Related FAQs: How do I play an XMIDI or MIDI file?