wxMidi messages

Raw MIDI messages are just a stream of bytes. The so called 'short messages' are the most common and are at most just three bytes but, in general, raw MIDI messages will vary from one byte to an arbitrary number of bytes.

In the wxMidi package MIDI messages will be represented by a wxMidiMessage object, that contains information about the type, data length, and status byte of the raw MIDI message for which it serves as a wrapper. In addition, it provides a timestamp value that is used by devices involved in MIDI timing, such as sequencers.

There are two categories of messages, each represented by a wxMidiMessage subclass:

In addition, for now the wxMidi interface allows you to use the native portmidi message format, represented by the wxMidiPmMessage data type, that is just a long word containing the three bytes of a MIDI short message or, in case of sysex messages, four bytes of a chunk of a sysex message. It is recommended not to use this format as it is not guaranteed to be maintained in future versions of wxMidi. Should you have the necessity of using it, I would very much appreciate an e-mail explaining the reason so that the wxMidi interface can be better designed. wxMidiPmMessage is not directly use by methods Write() or Read(). Insted, a more complex data structure is used for this, the wxMidiPmEvent struct. It is just a wxMidiPmMessage plus a timestamp.

wxMidiMessage
wxMidiShortMessage
wxMidiSysExMessage


wxMidiMessage

In the wxMidi package MIDI messages will be represented by a wxMidiMessage object, It is an abstract class from which the specific Midi messages derive. It contains information about the type, data length, and status byte of the MIDI message. In addition, it provides a timestamp value that is used by devices involved in MIDI timing, such as sequencers.

See also:

wxMidiShortMessage, wxMidiSysExMessage

Members

wxMidiMessage::wxMidiMessage
wxMidiMessage::~wxMidiMessage
wxMidiMessage::GetStatus
wxMidiMessage::GetTimestamp
wxMidiMessage::GetType
wxMidiMessage::SetTimestamp


wxMidiMessage::wxMidiMessage

wxMidiMessage()

Constructor.


wxMidiMessage::~wxMidiMessage

~wxMidiMessage()

Destructor.


wxMidiSystem::GetStatus

wxByte GetStatus()

Returns the status byte of the message.

For a wxSysExMessage status byte is always 0xF0 but the end of sysex message (0xF7) is also included in the message data. According MIDI standard the most significative bit of the status byte is always 1 so the range of staus values goes from 0x80 to 0xFF.

Values lower than 0xF0 identify channel messages, with the four lower bits specifying the channel (0-15); for example, status byte 0x93 is a NoteOn for channel 3:

Note-Off Event0x8n
Note-On Event0x9n
Polyphonic Key Pressure0xAn
Control Change0xBn
Program Change0xCn
Channel Pressure0xDn
Pitch Bend0xEn

 

Values 0xF0 to 0xFF are for system messages and are no intended for a specific channel:

Begin System Exclusive0xF0
MIDI Time Code0xF1
Song Position Pointer0xF2
Song Select0xF3
Tune Request0xF6
End System Exclusive0xF7
Real-time Clock0xF8
Undefined0xF9
Start0xFA
Continue0xFB
Stop0xFC
Undefined0xFD
Active Sensing0xFE
System Reset0xFF


wxMidiMessage::GetTimestamp

wxMidiTimestamp GetTimestamp()

Returns the message timestamp value. On input, the timestamp ideally denotes the arrival time of the status byte of the message.


wxMidiMessage::GetType

wxMidiMsgType GetType()

Returns either wxMIDI_SHORT_MSG, or wxMIDI_SYSEX_MSG, identifying the type of message object.


wxMidiMessage::SetTimestamp

void SetTimestamp(long timestamp)

Set the message timestamp value. On output to a wxMidiOutDevice opened with non-zero latency, the timestamp will determine the time to begin sending the message. If the wxMidiOutDevice was opened with a latency value of zero, timestamps will be ignored and messages will be delivered inmediatelly.

Parameters

timestamp


wxMidiShortMessage

wxMidiShortMessage are the most common and have a status byte and at most two data bytes.

Derived from:

wxMidiMessage

See also:

wxMidiMessage, wxMidiSysExMessage

Members

wxMidiShortMessage::wxMidiShortMessage
wxMidiShortMessage::~wxMidiShortMessage
wxMidiShortMessage::GetData1
wxMidiShortMessage::GetData2


wxMidiShortMessage::wxMidiShortMessage

wxMidiShortMessage(wxByte status, wxByte data1, wxByte data2) wxMidiShortMessage()

Constructor.


wxMidiShortMessage::~wxMidiShortMessage

~wxMidiShortMessage()

Destructor.


wxMidiShortMessage::GetData1

wxByte GetData1()

Returns the first data byte of the message or 0x00 if the type of message only has the status byte.


wxMidiShortMessage::GetData2

wxByte GetData2()

Returns the second data byte of the message or 0x00 if the type of message only has one data byte.


wxMidiSysExMessage

Object wxMidiSysExMessage represents a system-exclusive MIDI message. As the MIDI specification allows that sysex messages be interrupted by real-time messages, the wxMidi package takes care of this and ensures that any real-time messsage embeded into a sysex message will be delivered first. Also it ensures that when a sysex message is delivered it is complete and does not contain real-time messages embeded into it.

The sysex message encapsulated in a wxMidiSysExMessage will normally be terminated by an EOX status byte (0xF7), but this can not be guaranteed. If the last byte of a received wxMidiSysExMessage is not an EOX it means the sysex message was somehow truncated. This is not considered an error, as a missing EOX can result from the user disconnecting a MIDI cable during sysex transmission.

The timestamp of a wxMidiSysExMessage is the time at which the status byte (the first byte of the message) arrived.

Derived from:

wxMidiMessage

See also:

wxMidiMessage, wxMidiShortMessage

Members

wxMidiSysExMessage::wxMidiSysExMessage
wxMidiSysExMessage::~wxMidiSysExMessage
wxMidiSysExMessage::Error
wxMidiSysExMessage::GetMessage
wxMidiSysExMessage::Length
wxMidiSysExMessage::SetBuffer
wxMidiSysExMessage::SetLength


wxMidiSysExMessage::wxMidiSysExMessage

wxMidiSysExMessage()

Default constructor, intended for wxMidi internal use.

wxMidiSysExMessage(wxByte* msg, wxMidiTimestamp timestamp=0)

Constructor, creating a wxMidiSysExMessage object from a string of wxBytes. In case of error during construction, subsecuents calls to wxMidiSysExMessage::Error will return a error code with more information about the error.

Parameters

msg

timestamp


wxMidiSysExMessage::~wxMidiSysExMessage

~wxMidiSysExMessage()

Destructor.


wxMidiSysExMessage::Error

wxMidiError Error()

Returns the error code for the wxMidiSysExMessage constructor.

When building the wxMidiSysExMessage in one step, copying data from a wxByte string, some checking is done, for example, to verify that the message starts with a start-of-sysex status byte (0xF0) and that the buffer ends with an end-of-sysex status byte (0xF7). If any error is detected, the error is recorded and is returned when this method is called.

If no error, zero (wxMIDI_NO_ERROR) is returned.

See also:

wxMidi error codes, wxMidiSysExMessage constructor


wxMidiSysExMessage::GetMessage

wxByte* GetMessage()

Returns a wxByte string containing the raw MIDI message. It includes the start-of-sysex status byte (0xF0) and the end-of-sysex status byte (0xF7) - unless it is a truncated sysex message - . See wxMidiSysExMessage

The returned string is owned by the wxMidiSysExMessage and must not be deleted.


wxMidiSysExMessage::Length

int Length()

Returns the length (number of bytes) of the message returned by wxMidiSysExMessage::GetMessage. It is, the length, in bytes, of the raw MIDI message, not the length of the buffer containing it.


wxMidiSysExMessage::SetBuffer

void SetBuffer(wxByte* pBuffer)

This method is mainly intended for internal use of wxMidi. It stores the pointer received as parameter, so that internal buffer will point to the received string. The wxMidiSysExMessage object will become the owner of the string and will be deleted in the destructor. User must not delete the passed buffer.

The lenght of the passed string must be set by calling wxMidiSysExMessage::SetLength.


wxMidiSysExMessage::SetLength

void SetLength(int lenght)

This method is mainly intended for internal use of wxMidi. It stores the lentgh of the wxByte string received in a previous call to wxMidiSysExMessage::SetBuffer (or to be received in a subsequent call to that method). The value pased as parameter must be the real size of the raw MIDI message not the size of the buffer containing it, that could be greater.