OpenJDK 1.23 · javax.sound.midi.SysexMessage · APIdia, the JavaDoc alternative

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.

Field Summary

Modifier and Type	Field and Description
public static final int	SPECIAL_SYSTEM_EXCLUSIVE Status byte for Special System Exclusive message (0xF7, or 247), which is used in MIDI files.
public static final int	SYSTEM_EXCLUSIVE Status byte for System Exclusive message (0xF0, or 240).

Inherited from javax.sound.midi.MidiMessage:: data length

Constructor Summary

Access	Constructor and Description
public	SysexMessage() Constructs a new `SysexMessage`.
public	SysexMessage(byte[] the system exclusive message data including the status byte data, int the length of the valid message data in the array, including the status byte; it should be non-negative and less than or equal to `data.length` length) Constructs a new `SysexMessage` and sets the data for the message.
public	SysexMessage(int the status byte for the message; it must be a valid system exclusive status byte (0xF0 or 0xF7) status, byte[] the system exclusive message data (without the status byte) data, int the length of the valid message data in the array; it should be non-negative and less than or equal to `data.length` length) Constructs a new `SysexMessage` and sets the data for the message.
protected	SysexMessage(byte[] an array of bytes containing the complete message. The message data may be changed using the `setMessage` method. data) Constructs a new `SysexMessage`.

Method Summary

Modifier and Type	Method and Description
public Object	Returns: a clone of this instance clone() Implements abstract javax.sound.midi.MidiMessage.clone. Creates a new object of the same class and with the same contents as this object.
public byte[]	Returns: array containing the system exclusive message data getData() Obtains a copy of the data for the system exclusive message.
public void	setMessage(byte[] the system exclusive message data data, int the length of the valid message data in the array, including the status byte length) Overrides javax.sound.midi.MidiMessage.setMessage. Sets the data for the system exclusive message.
public void	setMessage(int the status byte for the message (0xF0 or 0xF7) status, byte[] the system exclusive message data data, int the length of the valid message data in the array length) Sets the data for the system exclusive message.

Inherited from javax.sound.midi.MidiMessage:: getLength getMessage getStatus

Field Detail

SPECIAL_SYSTEM_EXCLUSIVE back to summary

SPECIAL_SYSTEM_EXCLUSIVE	back to summary
public static final int SPECIAL_SYSTEM_EXCLUSIVE Status 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. See Also `MidiMessage#getStatus`

public static final int SPECIAL_SYSTEM_EXCLUSIVE

Status 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.

See Also: MidiMessage#getStatus

SYSTEM_EXCLUSIVE back to summary

SYSTEM_EXCLUSIVE	back to summary
public static final int SYSTEM_EXCLUSIVE Status byte for System Exclusive message (0xF0, or 240). See Also `MidiMessage#getStatus`

public static final int SYSTEM_EXCLUSIVE

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

See Also: MidiMessage#getStatus

Constructor Detail

SysexMessage back to summary

SysexMessage	back to 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. See Also `setMessage`

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.

See Also: setMessage

SysexMessage back to summary

SysexMessage	back to summary
public SysexMessage(byte[] data, int length) throws InvalidMidiDataException Constructs a new `SysexMessage` and sets the data for the message. The first byte of the data array must be a valid system exclusive status byte (0xF0 or 0xF7). The contents of the message can be changed by using one of the `setMessage` methods. Parameters data:byte[] the system exclusive message data including the status byte length:int the length of the valid message data in the array, including the status byte; it should be non-negative and less than or equal to `data.length` Exceptions InvalidMidiDataException: if the parameter values do not specify a valid MIDI meta message Since 1.7 See Also `setMessage(byte[], int)`, `setMessage(int, byte[], int)`, `getData()`

public SysexMessage(byte[] data, int length) throws InvalidMidiDataException

Constructs a new SysexMessage and sets the data for the message. The first byte of the data array must be a valid system exclusive status byte (0xF0 or 0xF7). The contents of the message can be changed by using one of the setMessage methods.

Parameters

data:byte[]: the system exclusive message data including the status byte
length:int: the length of the valid message data in the array, including the status byte; it should be non-negative and less than or equal to data.length

Exceptions

InvalidMidiDataException:: if the parameter values do not specify a valid MIDI meta message

Since

1.7

SysexMessage back to summary

SysexMessage	back to summary
public SysexMessage(int status, byte[] data, int length) throws InvalidMidiDataException Constructs a new `SysexMessage` and sets the data for the message. The contents of the message can be changed by using one of the `setMessage` methods. Parameters status:int the status byte for the message; it must be a valid system exclusive status byte (0xF0 or 0xF7) data:byte[] the system exclusive message data (without the status byte) length:int the length of the valid message data in the array; it should be non-negative and less than or equal to `data.length` Exceptions InvalidMidiDataException: if the parameter values do not specify a valid MIDI system exclusive message Since 1.7 See Also `setMessage(byte[], int)`, `setMessage(int, byte[], int)`, `getData()`

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

Constructs a new SysexMessage and sets the data for the message. The contents of the message can be changed by using one of the setMessage methods.

Parameters

status:int: the status byte for the message; it must be a valid system exclusive status byte (0xF0 or 0xF7)
data:byte[]: the system exclusive message data (without the status byte)
length:int: the length of the valid message data in the array; it should be non-negative and less than or equal to data.length

Exceptions

InvalidMidiDataException:: if the parameter values do not specify a valid MIDI system exclusive message

Since

1.7

SysexMessage back to summary

SysexMessage	back to summary
protected SysexMessage(byte[] data) Constructs a new `SysexMessage`. Parameters data:byte[] an array of bytes containing the complete message. The message data may be changed using the `setMessage` method. See Also `setMessage`

protected SysexMessage(byte[] data)

Constructs a new SysexMessage.

Parameters

data:byte[]: an array of bytes containing the complete message. The message data may be changed using the setMessage method.

See Also

setMessage

Method Detail

clone	back to summary
public Object clone() Implements abstract javax.sound.midi.MidiMessage.clone. Creates a new object of the same class and with the same contents as this object. Returns:Object a clone of this instance Annotations @Override

clone

back to summary

public Object clone()

Implements abstract javax.sound.midi.MidiMessage.clone.

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

Returns:Object

a clone of this instance

Annotations

@Override

getData	back to summary
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. Returns:byte[] array containing the system exclusive message data

getData

back to summary

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.

Returns:byte[]: array containing the system exclusive message data

setMessage	back to summary
public void setMessage(byte[] data, int length) throws InvalidMidiDataException Overrides javax.sound.midi.MidiMessage.setMessage. 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). Parameters data:byte[] the system exclusive message data length:int the length of the valid message data in the array, including the status byte Annotations @Override Exceptions InvalidMidiDataException: if the parameter values do not specify a valid MIDI system exclusive message

setMessage

back to summary

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

Overrides javax.sound.midi.MidiMessage.setMessage.

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).

Parameters

data:byte[]: the system exclusive message data
length:int: the length of the valid message data in the array, including the status byte

Annotations

@Override

Exceptions

InvalidMidiDataException:: if the parameter values do not specify a valid MIDI system exclusive message

setMessage	back to summary
public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException Sets the data for the system exclusive message. Parameters status:int the status byte for the message (0xF0 or 0xF7) data:byte[] the system exclusive message data length:int the length of the valid message data in the array Exceptions InvalidMidiDataException: if the status byte is invalid for a system exclusive message

setMessage

back to summary

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

Sets the data for the system exclusive message.

Parameters

status:int: the status byte for the message (0xF0 or 0xF7)
data:byte[]: the system exclusive message data
length:int: the length of the valid message data in the array

Exceptions

InvalidMidiDataException:: if the status byte is invalid for a system exclusive message

public Class SysexMessage

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail