Miles Sound System SDK 7.2a

AIL_lock_channel

The function AIL_lock_channel returns an individual MIDI channel number to the application for direct MIDI message transmission, preventing any XMIDI sequence from utilizing that physical channel until its release with AIL_release_channel.

S32 AIL_lock_channel(
  HMDIDRIVER mdi
);

In Parameters

mdi

Returns

A physical MIDI channel number from 1 to 16, or 0 if no unlocked channels were available.

Discussion

Parameters mdi specifies the driver which is to supply the locked physical channel.

MIDI channel numbers are passed to and from the MSS API in 1-based format (1-16), rather than the 0-based format (0-15) used when composing MIDI Status byte values.

This function is useful for "one-shot" sound effects which require a MIDI channel to be temporarily set aside from the normal background playback process. When accessed from within an XMIDI sequence by use of the XMIDI Channel Lock controller (110), channel locking is invaluable in overlaying sound effect sequences over a "background" score. See the Extended MIDI Specification Section for an overview of channel locking, remapping, and multiple-sequence playback.

AIL_lock_channel attempts to return the highest MIDI channel number recognized by the driver's supported synthesizer which has the fewest actively playing notes. Channels which are already locked will not be returned. Channels which have been "protected" against locking by use of the XMIDI Channel Lock Protect controller (111), will not be returned unless all other channels are locked. If no available MIDI channels are eligible for locking under these criteria, the function returns a value of 0. Otherwise, the returned channel number may range from 1 to 16, but is normally restricted to the range 2 through 9 for compatibility with a broader range of synthesizers.

Before the channel number is returned to the application, the MIDI Sustain (Hold1) controller (64) in the channel is forced to its "off" condition, and all notes playing in the channel are silenced. No other controller values or MIDI messages are initialized! It is essential for an application (or a sequence) which has just received a locked channel to initialize all MIDI parameters, including MIDI controllers, the XMIDI Patch Bank Select controller and MIDI Program Change number, and the MIDI pitch wheel, to appropriate values.

The application should use AIL_send_channel_voice_message with a NULL HSEQUENCE parameter to send MIDI and XMIDI Channel Voice messages on the locked channel. No other API function will communicate directly with a locked channel. The locked channel should be returned to the driver with AIL_release_channel as soon as it is no longer needed by the application.

Group: XMIDI Services
Related Sections: XMIDI Channel Lock (110), XMIDI Channel Lock Protect (111)
Related Functions: AIL_lock_channel, AIL_release_channel, AIL_send_channel_voice_message
Related Basic Types: HMDIDRIVER, S32