SysexMessagepublic class SysexMessage extends MidiMessage 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. |
| Fields Summary |
|---|
| public static final int | SYSTEM_EXCLUSIVEStatus byte for System Exclusive message (0xF0, or 240). | | public static final int | SPECIAL_SYSTEM_EXCLUSIVEStatus byte for Special System Exclusive message (0xF7, or 247), which is used
in MIDI files. It has the same value as END_OF_EXCLUSIVE, which
is used in the real-time "MIDI wire" protocol. |
| Constructors Summary |
|---|
public 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. // 247
// Instance variables
/*
* The data bytes for this system exclusive message. These are
* initialized to <code>null</code> and are set explicitly
* by {@link #setMessage(int, byte[], int, long) setMessage}.
*/
//protected byte[] data = null;
this(new byte[2]);
// Default sysex message data: SOX followed by EOX
data[0] = (byte) (SYSTEM_EXCLUSIVE & 0xFF);
data[1] = (byte) (ShortMessage.END_OF_EXCLUSIVE & 0xFF);
| protected SysexMessage(byte[] data)Constructs a new SysexMessage.
super(data);
|
| Methods Summary |
|---|
| public java.lang.Object | clone()Creates a new object of the same class and with the same contents
as this object.
byte[] newData = new byte[length];
System.arraycopy(data, 0, newData, 0, newData.length);
SysexMessage event = new SysexMessage(newData);
return event;
| | public byte[] | getData()Obtains a copy of the data for the system exclusive message.
The returned array of bytes does not include the status byte.
byte[] returnedArray = new byte[length - 1];
System.arraycopy(data, 1, returnedArray, 0, (length - 1));
return returnedArray;
| | public void | setMessage(byte[] data, int length)Sets the data for the system exclusive message. The
first byte of the data array must be a valid system
exclusive status byte (0xF0 or 0xF7).
int status = (data[0] & 0xFF);
if ((status != 0xF0) && (status != 0xF7)) {
throw new InvalidMidiDataException("Invalid status byte for sysex message: 0x" + Integer.toHexString(status));
}
super.setMessage(data, length);
| | public void | setMessage(int status, byte[] data, int length)Sets the data for the system exclusive message.
if ( (status != 0xF0) && (status != 0xF7) ) {
throw new InvalidMidiDataException("Invalid status byte for sysex message: 0x" + Integer.toHexString(status));
}
if (length < 0 || length > data.length) {
throw new IndexOutOfBoundsException("length out of bounds: "+length);
}
this.length = length + 1;
if (this.data==null || this.data.length < this.length) {
this.data = new byte[this.length];
}
this.data[0] = (byte) (status & 0xFF);
if (length > 0) {
System.arraycopy(data, 0, this.data, 1, length);
}
|
|
