BASS.NET API for the Un4seen BASS Audio Library

MidiSysExMessage Class

BASS.NET API for the Un4seen BASS Audio Library
This class represents a Midi system-exclusive message as for example received in a MIM_LONGDATA message of a MIDIINPROC or as being used with the MIDI_OutLongMsg(IntPtr, IntPtr) and returned back in the MIDIOUTPROC with the MOM_DONE message.
Inheritance Hierarchy

SystemObject
  radio42.Multimedia.MidiMidiSysExMessage

Namespace:  radio42.Multimedia.Midi
Assembly:  Bass.Net (in Bass.Net.dll) Version: 2.4.17.5
Syntax

[SerializableAttribute]
public sealed class MidiSysExMessage

The MidiSysExMessage type exposes the following members.

Constructors

  NameDescription
Public methodMidiSysExMessage(Boolean, IntPtr)
Creates a new and empty instance of the MidiSysExMessage.
Public methodMidiSysExMessage(Boolean, IntPtr, IntPtr)
Creates a new instance of the MidiSysExMessage from a pointer to a MIDI_HEADER.
Public methodMidiSysExMessage(Boolean, IntPtr, IntPtr, MidiSysExMessage)
Creates a new instance of the MidiSysExMessage from a pointer to a MIDI_HEADER and also evaluates a previous system-exclusive message.
Top
Properties

  NameDescription
Public propertyDevice
Gets the handle to the MIDI device.
Public propertyID
Gets a unique overall short message ID.
Public propertyIsDone
, if the data in the buffer is complete and contains all data (else ).
Public propertyIsInput
Dealing with a Midi input device? (=input, =output).
Public propertyIsPrepared
Returns , if the Message data buffer is prepared and can not be changed anymore (else ).
Public propertyIsUniversalNonRealtime
, if the system-exclusive message contains a Manufacturer ID of NonRealTime.
Public propertyIsUniversalRealtime
, if the system-exclusive message contains a Manufacturer ID of RealTime.
Public propertyManufacturer
Gets the manufacturer ID from a system-exclusive message (or -32768 if not applicable or no Message data buffer is present).
Public propertyMessage
Gets the raw data buffer bytes representing the system-exclusive message.
Public propertyMessageAsIntPtr
Gets the prepared pointer to the MIDI_HEADER structure ready to be used with a Midi device.
Public propertyMessageLength
Gets the length of the system exclusive Message data buffer.
Public propertyMessageType
Gets the Midi message type (one of the MIDIMessageType values).
Public propertyMMCCommand
Gets the MMC Device ID (or 255 on error or not present).
Public propertyMMCDeviceID
Gets the MMC Device ID (or 255 on error or not present).
Public propertyStatusType
Gets the Midi status type (one of the MIDIStatus values) from the first byte of the Message data buffer.
Public propertyUniversalChannel
Gets the Universal SysEx Channel number (or 255 on error or not present).
Public propertyUniversalSubID
Gets the Universal SysEx Sub ID (or 255 on error or not present).
Public propertyUniversalSubID2
Gets the Universal SysEx Sub ID (or 255 on error or not present).
Public propertyUser
Gets the user instance data as passed with the Prepare method.
Top
Methods

  NameDescription
Public methodCreateBuffer(Byte)
Creates a Message data buffer with the given data buffer.
Public methodCreateBuffer(Int32)
Creates an empty Message data buffer of the given size (between 2 and 65536).
Public methodMessageRead
Reads an 8-bit value from the Message data buffer (full).
Public methodMessageRead16
Reads a 14-bit value (2 bytes) from the Message data buffer (right-justified).
Public methodMessageRead16Wave
Reads a 16-bit waveform value (3 bytes) from the Message data buffer (left-justified).
Public methodMessageRead24
Reads a 21-bit value (3 bytes) from the Message data buffer (right-justified).
Public methodMessageRead24Wave
Reads a 24-bit waveform value (4 bytes) from the Message data buffer (left-justified).
Public methodMessageRead32
Reads a 28-bit value (4 bytes) from the Message data buffer (right-justified).
Public methodMessageRead8
Reads a 7-bit value from the Message data buffer (right-justified).
Public methodMessageRead8Wave
Reads an 8-bit waveform value (2 bytes) from the Message data buffer (left-justified).
Public methodCode exampleMessageWrite
Writes an 8-bit value to the Message data buffer (full).
Public methodMessageWrite16
Writes a 14-bit value (2 bytes) to the Message data buffer (right-justified).
Public methodMessageWrite16Wave(Int32, Int16)
Writes a 16-bit waveform value (3 bytes) to the Message data buffer (left-justified).
Public methodMessageWrite16Wave(Int32, Int32)
Writes a 24-bit waveform value (4 bytes) to the Message data buffer (left-justified).
Public methodMessageWrite24
Writes a 21-bit value (3 bytes) to the Message data buffer (right-justified).
Public methodMessageWrite32
Writes a 28-bit value (4 bytes) to the Message data buffer (right-justified).
Public methodMessageWrite8
Writes a 7-bit value to the Message data buffer (right-justified).
Public methodMessageWrite8Wave
Writes an 8-bit waveform value (2 bytes) to the Message data buffer (left-justified).
Public methodMessageWriteEoX
Writes the EOX byte (0xF7) to the last byte of the Message data buffer.
Public methodMessageWriteSoX
Writes the SystemMsgs byte (0xF0) to the first byte of the Message data buffer.
Public methodPrepare
Prepares the MessageAsIntPtr out of the Message data buffer ready to be used with a device.
Public methodPrepare(IntPtr)
Prepares the MessageAsIntPtr out of the Message data buffer ready to be used with a device.
Public methodSend
Sends this system-exclusive message to the given Device.
Public methodToString
Returns the Message data buffer as a string.
(Overrides ObjectToString.)
Public methodValidate
Validates the given Message data buffer to ensure it contains a valid system-exclusive message.
Top
Remarks

You might use the class to pack (encode, construct) or unpack (decode) any Midi system-exclusive message.

System-Exclusive message use a MIDI_HEADER structure as the transport vehicle between devices. Internally a Message data buffer needs to be prepared when sending or providing the buffer to a device. When the device finishes with the message processing you will be notified and you'll need to unprepare the buffer.

Sending system-exclusive messages to an output device:

Use this class with the MIDI_OutLongMsg(IntPtr, IntPtr) method to send a message to an output device. Beforehand use the CreateBuffer(Int32) method to construct your message buffer. You might then use the MessageWrite(Int32, Byte) methods to write data to the Message data buffer. When done call the Prepare method to prepare the data buffer and make it ready to be send to the device. Once prepared the data buffer can not be changed anymore. Finally use the MessageAsIntPtr property in the MIDI_OutLongMsg(IntPtr, IntPtr) call to get the pointer to the constructed and prepared MIDI_HEADER structure. After sending the message make sure to capture the MOM_DONE message in your MIDIOUTPROC in order to unprepare the data buffer. This is actually automatically being done within the constructor of this class when using the overload taking an IntPtr argument.

Receiving system-exclusive messages at an input device:

Use this class with the MIM_LONGDATA message of a MIDIINPROC to decode the received message. Before you can receive system-exclusive messages you must constantly provide data buffers to the device (which will then be filled with data by the device and returned to your input). So you might use the CreateBuffer(Int32) method to create such empty buffer and then call Prepare to prepare the data buffer and make it ready to be send to the device. Once prepared the data buffer can not be changed anymore. Finally use the MessageAsIntPtr property in the MIDI_InAddBuffer(IntPtr, IntPtr) call to get the pointer to the constructed and prepared MIDI_HEADER structure and provide the buffer to the device. After providing the buffer make sure to capture the MIM_LONGDATA resp. MIM_LONGERROR message in your MIDIINPROC in order to unprepare the data buffer. This is actually automatically being done within the constructor of this class when using the overload taking an IntPtr argument. You might use the MessageRead8(Int32), MessageRead16(Int32), MessageRead24(Int32) etc. methods to fianlly read data from the Message data buffer you received and interpret it's content accordingly.

The MidiInputDevice and MidiOutputDevice already handle most of these tasks (e.g. preparing and unpreparing of system-exclusive messages) for you.

Examples

Sending system-exclusive messages to an output device:
private MIDIOUTPROC _midiProc;
private IntPtr _midiOutHandle;
...
// Open the Midi device #0
_midiProc = new MIDIOUTPROC(MyMidiOutProc);
MIDIError ret = Midi.MIDI_OutOpen(ref _midiOutHandle, 0, _midiProc, 0);
if (ret == MIDIError.MIDI_OK)
{
  // output ready
}
...
private void SendSysExBuffer(IntPtr handle, byte[] data)
{
  MidiSysExMessage msg = new MidiSysExMessage(false, handle);
  msg.CreateBuffer(data);
  if (msg.Prepare())
  {
    // if the message was perpared successfully
    // send a system-exclusive message to the output device
    Midi.MIDI_OutLongMsg(handle, msg.MessageAsIntPtr);
  }
}

public void MyMidiOutProc(IntPtr handle, MIDIMessage msg, IntPtr instance, IntPtr param1, IntPtr param2)
{
  // handle all Midi messages here
  if (msg == MIDIMessage.MOM_DONE)
  {
    // process the message...
    // param1 will contain the pointer to the MIDI_HEADER
    MidiSysExMessage sysexMsg = new MidiSysExMessage(false, handle, param1);
    // the internal header is already unprepared here
    // so you can still use the data...
    Console.WriteLine( sysexMsg.ToString() );
  }
  ...
}
Receiving system-exclusive messages at an input device:
private MIDIINPROC _midiProc;
private IntPtr _midiInHandle;
...
// Open the Midi device #0
_midiProc = new MIDIINPROC(MyMidiInProc);
MIDIError ret = Midi.MIDI_InOpen(ref _midiInHandle, 0, _midiProc, IntPtr.Zero, MIDIFlags.MIDI_IO_STATUS);
if (ret == MIDIError.MIDI_OK)
{
  // already supply the device with 2 buffers (each 1K)
  AddSysExBuffer(_midiInHandle, 1024);
  AddSysExBuffer(_midiInHandle, 1024);
  // Start the device
  ret = Midi.MIDI_InStart(_midiInHandle);
}
...
// prepare receiving system-exclusive messages
private void AddSysExBuffer(IntPtr handle, int size)
{
  MidiSysExMessage msg = new MidiSysExMessage(true, handle);
  msg.CreateBuffer(size);
  if (msg.Prepare())
  {
    // Add the buffer to the InputDevice.
    Midi.MIDI_InAddBuffer(handle, msg.MessageAsIntPtr);
  }
}

MidiSysExMessage _sysexMsg = null;
public void MyMidiInProc(IntPtr handle, MIDIMessage msg, IntPtr instance, IntPtr param1, IntPtr param2)
{
  if (msg == MIDIMessage.MIM_LONGDATA || msg == MIDIMessage.MIM_LONGERROR)
  {
    // process the sysex message...
    // param1 will contain the pointer to the MIDI_HEADER
    _sysexMsg = new MidiSysExMessage(true, handle, param1, _sysexMsg);
    if (_sysexMsg.IsDone)
    {
      // use it...
      Console.WriteLine( sysexMsg.ToString() );
    }
    ...
    // add a new buffer
    // since we should constantly provide new buffers until we finished recording
    AddSysExBuffer(handle, 1024);
  }
  ...
}
See Also

Reference