SysexMessage JDK 1.6)

Description

public class SysexMessage

A SysexMessage object represents a MIDI system exclusive message.

When a system exclusive message is read from a MIDI file, it always has a defined length. Data from a system exclusive message from a MIDI file should be stored in the data array of a SysexMessage as follows: the system exclusive message status byte (0xF0 or 0xF7), all message data bytes, and finally the end-of-exclusive flag (0xF7). The length reported by the SysexMessage object is therefore the length of the system exclusive data plus two: one byte for the status byte and one for the end-of-exclusive flag.

As dictated by the Standard MIDI Files specification, two status byte values are legal for a SysexMessage read from a MIDI file:

0xF0: System Exclusive message (same as in MIDI wire protocol)
0xF7: Special System Exclusive message

When Java Sound is used to handle system exclusive data that is being received using MIDI wire protocol, it should place the data in one or more SysexMessages. In this case, the length of the system exclusive data is not known in advance; the end of the system exclusive data is marked by an end-of-exclusive flag (0xF7) in the MIDI wire byte stream.

0xF0: System Exclusive message (same as in MIDI wire protocol)
0xF7: End of Exclusive (EOX)

The first SysexMessage object containing data for a particular system exclusive message should have the status value 0xF0. If this message contains all the system exclusive data for the message, it should end with the status byte 0xF7 (EOX). Otherwise, additional system exclusive data should be sent in one or more SysexMessages with a status value of 0xF7. The SysexMessage containing the last of the data for the system exclusive message should end with the value 0xF7 (EOX) to mark the end of the system exclusive message.

If system exclusive data from SysexMessages objects is being transmitted using MIDI wire protocol, only the initial 0xF0 status byte, the system exclusive data itself, and the final 0xF7 (EOX) byte should be propagated; any 0xF7 status bytes used to indicate that a SysexMessage contains continuing system exclusive data should not be propagated via MIDI wire protocol.

See also:

Constructors

public SysexMessage ()

Constructs a new SysexMessage.

Constructs a new SysexMessage. The
contents of the new message are guaranteed to specify
a valid MIDI message. Subsequently, you may set the
contents of the message using one of the setMessage
methods.
See Also: SysexMessage.setMessage(byte[], int),

protected SysexMessage (byte[] data)

Constructs a new SysexMessage.

Constructs a new SysexMessage.
Parameters:
- data - an array of bytes containing the complete message. The message data may be changed using the setMessage method.
See Also: SysexMessage.setMessage(byte[], int),

Methods

Hide/Show inherited methods

public Object clone () [Specified in MidiMessage]

Creates a new object of the same class and with the same contents as this object.

public byte getData ()

Obtains a copy of the data for the system exclusive message.

public int getLength () [Inherited From MidiMessage]

Obtains the total length of the MIDI message in bytes.

public byte getMessage () [Inherited From MidiMessage]

Obtains the MIDI message data.

Obtains the MIDI message data. The first byte of the returned byte
array is the status byte of the message. Any subsequent bytes up to
the length of the message are data bytes. The byte array may have a
length which is greater than that of the actual message; the total
length of the message in bytes is reported by the MidiMessage.getLength()
method.
Returns: the byte array containing the complete MidiMessage data

public int getStatus () [Inherited From MidiMessage]

Obtains the status byte for the MIDI message.

Obtains the status byte for the MIDI message. The status "byte" is
represented as an integer; see the
discussion in the
MidiMessage class description.
Returns: the integer representation of this event's status byte

public void setMessage (byte[] data, int length) throws InvalidMidiDataException [Overrides MidiMessage]

Sets the data for the system exclusive message.

public void setMessage (int status, byte[] data, int length) throws InvalidMidiDataException

Sets the data for the system exclusive message.

Fields

Hide/Show inherited fields

protected byte data [Inherited From MidiMessage]

The MIDI message data.

protected int length [Inherited From MidiMessage]

The number of bytes in the MIDI message, including the status byte and any data bytes.

publicfinalstatic int SPECIAL_SYSTEM_EXCLUSIVE = "247"

Status byte for Special System Exclusive message (0xF7, or 247), which is used in MIDI files.

publicfinalstatic int SYSTEM_EXCLUSIVE = "240"

Status byte for System Exclusive message (0xF0, or 240).