wxMidi - A MIDI interface based on PortMidi
Public Member Functions | List of all members
wxMidiSysExMessage Class Reference

Represents a system-exclusive MIDI message. More...

#include <wxMidi.h>

Inheritance diagram for wxMidiSysExMessage:
wxMidiMessage

Public Member Functions

 wxMidiSysExMessage (wxByte *msg, wxMidiTimestamp timestamp=0)
 Constructor, creating a wxMidiSysExMessage object from a string of wxBytes. More...
 
 wxMidiSysExMessage ()
 Default constructor, intended for wxMidi internal use.
 
 ~wxMidiSysExMessage ()
 Destructor.
 
void SetTimestamp (wxMidiTimestamp timestamp)
 Set the message timestamp value. More...
 
wxMidiTimestamp GetTimestamp ()
 
wxByte GetStatus ()
 Returns the status byte of the message. More...
 
wxByte * GetMessage ()
 Returns a wxByte string containing the raw MIDI message. More...
 
wxMidiError Error ()
 Returns the error code for the wxMidiSysExMessage constructor. More...
 
long Length ()
 Returns the length (number of bytes) of the message returned by GetMessage(). More...
 
void SetBuffer (wxByte *pBuffer)
 This method is mainly intended for internal use of wxMidi. More...
 
void SetLength (long lenght)
 This method is mainly intended for internal use of wxMidi. More...
 
- Public Member Functions inherited from wxMidiMessage
 wxMidiMessage ()
 Constructor.
 
virtual ~wxMidiMessage ()
 Destructor.
 
wxMidiMsgType GetType ()
 Returns either wxMIDI_SHORT_MSG, or wxMIDI_SYSEX_MSG, identifying the type of the message object. More...
 

Additional Inherited Members

- Protected Attributes inherited from wxMidiMessage
wxMidiMsgType m_type
 

Detailed Description

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 message embedded 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 embedded into it.

The sysex message encapsulated in a wxMidiSysExMessage will be normally ended 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.

See also
wxMidiMessage, wxMidiShortMessage

Constructor & Destructor Documentation

◆ wxMidiSysExMessage()

wxMidiSysExMessage::wxMidiSysExMessage ( wxByte *  msg,
wxMidiTimestamp  timestamp = 0 
)

Constructor, creating a wxMidiSysExMessage object from a string of wxBytes.

In case of error during construction, subsequent calls to Error() will return a error code with more information about the error.

Parameters
msgThe raw MIDI message, as string of wxBytes. It must include the start-of-sysex status byte (0xF0) at the beginning and the end-of-sysex status byte (0xF7) at the end.
timestampThe timestamp value. It is milliseconds elapsed since the wxMidi package initialization. Current time can be obtained by calling wxMidi::GetTime(). Only meaningful if the wxOutDevice is open with latency time different from zero. In any case, if no timestamp is specified or if a value of zero is specified, the message will be delivered immediately. See wxMidiOutDevice::Write().

Member Function Documentation

◆ Error()

wxMidiError wxMidiSysExMessage::Error ( )
inline

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
error_codes, wxMidiSysExMessage()

◆ GetMessage()

wxByte* wxMidiSysExMessage::GetMessage ( )
inline

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.

◆ GetStatus()

wxByte wxMidiSysExMessage::GetStatus ( )
inlinevirtual

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 significant bit of the status byte is always 1 so the range of status 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:

Message Status byte
Note-Off Event 0x8n
Note-On Event 0x9n
Polyphonic Key Pressure0xAn
Control Change 0xBn
Program Change 0xCn
Channel Pressure 0xDn
Pitch Bend 0xEn

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

Message Status byte
Begin System Exclusive 0xF0
MIDI Time Code 0xF1
Song Position Pointer 0xF2
Song Select 0xF3
Tune Request 0xF6
End System Exclusive 0xF7
Real-time Clock 0xF8
Undefined 0xF9
Start 0xFA
Continue 0xFB
Stop 0xFC
Undefined 0xFD
Active Sensing 0xFE
System Reset 0xFF

Implements wxMidiMessage.

◆ Length()

long wxMidiSysExMessage::Length ( )
inline

Returns the length (number of bytes) of the message returned by GetMessage().

It is, the length, in bytes, of the raw MIDI message, not the length of the buffer containing it.

◆ SetBuffer()

void wxMidiSysExMessage::SetBuffer ( wxByte *  pBuffer)
inline

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 length of the passed string must be set by calling SetLength()

◆ SetLength()

void wxMidiSysExMessage::SetLength ( long  lenght)
inline

This method is mainly intended for internal use of wxMidi.

It stores the length of the wxByte string received in a previous call to SetBuffer() (or to be received in a subsequent call to that method).

The value passed as parameter must be the real size of the raw MIDI message not the size of the buffer containing it, that could be greater.

◆ SetTimestamp()

void wxMidiSysExMessage::SetTimestamp ( wxMidiTimestamp  timestamp)
inlinevirtual

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
timestampThe timestamp value. It is milliseconds elapsed since the wxMidi package initialization. Current time can be obtained by calling wxMidi::GetTime().

Implements wxMidiMessage.

The documentation for this class was generated from the following files: