Miles Sound System SDK 7.2a

AIL_send_channel_voice_message

The function AIL_send_channel_voice_message transmits any desired MIDI Channel Voice message on any MIDI channel.

void AIL_send_channel_voice_message(
  HMDIDRIVER mdi,
  HSEQUENCE S,
  S32 status,
  S32 data_1,
  S32 data_2
);

In Parameters

mdi: specifies the MIDI driver to which the MIDI Channel Voice message should be transmitted.
S: if not NULL, allows the Channel Voice message to be associated with a particular sequence's channel map and XMIDI event log.
status: is the MIDI status byte for the message to be transmitted.
data_1: is the first data byte for the message to be transmitted.
data_2: is the optional second data byte for the message to be transmitted.

Discussion

This function is often used to output "one-shot" sound effects on locked MIDI channels. See AIL_lock_channel for details.

Either the mdi or the S parameter may be set to NULL. If a driver but not a sequence is specified, the MIDI message will be sent directly to the synthesizer driver layer, with no XMIDI processing or channel remapping at all. On the other hand, when using this function to introduce new controller values "on the fly" into a playing XMIDI sequence, the sequence handle should be passed to the AIL_send_channel_voice_message rather than the driver. Access to a particular sequence handle will help MSS to track current controller values for the sequence, and will allow messages to be sent to channels which sequences have locked, without requiring any calls to AIL_true_sequence_channel.

Since the range of channel numbers recognized by different synthesizers can vary widely, it may be advisable to use this function only with physical channel numbers supplied by the AIL_lock_channel function when an explicit sequence handle is not used.

For a discussion of standard MIDI Channel Voice messages and their exact format, refer to De Furia and Scacciaferro's MIDI Programmer's Handbook, pp. 59-81, or to a similar general-purpose MIDI manual. Also refer to the MIDI Implementation Chart which accompanies each supported synthesizer.

It is import to note that the lower nibble of the status bytes consists of the MIDI channel number minus 1. This allows the full range of MIDI channels from 1 to 16 to be mapped into a single four-bit binary nibble, but may be a source of confusion since all other Miles Sound System API calls express channel numbers according to conventional 1-based MIDI notation. Unfortunately, "musician-perspective" versus "programmer-perspective" numbering conflicts are everyday occurrences in the field of MIDI programming.

data_2 should be set to 0 when transmitting Channel Voice messages which have no second data byte (such as Program Change and Channel Pressure messages).

Group: XMIDI Services
Related Sections: MIDIECHO for DOS - MIDI Data Receiver and Interpreter, MIDIECHO for MacOS - MIDI Data Receiver and Interpreter, MIDIECHO for Windows - MIDI Data Receiver and Interpreter, XMIDI Channel Mute (107)
Related Functions: AILEVENTCB, AIL_lock_channel, AIL_register_ICA_array, AIL_register_event_callback, AIL_send_channel_voice_message, AIL_send_sysex_message, AIL_true_sequence_channel
Related Basic Types: HMDIDRIVER, HSEQUENCE, S32, void