All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class jmidi.MidiPort

java.lang.Object
   |
   +----jmidi.MidiPort

public class MidiPort

extends Object

MidiPort wraps the device-dependent system calls necessary for reading and writing MIDI data to and from MIDI devices. Output can take two forms: short and long messages. Long messages are used for most System Exclusive commands; short messages are used for everything else. Input is buffered with a circular buffer, which can be read one message at a time. A method is provided indicating how many complete messages are in the buffer.

Before reading or writing, a MidiPort must be opened with the open() method. Before it is opened, the input and output device numbers must be specified, either in the MidiPort's constructor or using the setDeviceNumber() accessor. The number of valid devices and their names can be retrieved using the getNumDevices() and getDeviceName() methods. A Vector of devices of a given type can be obtained through a call to the method enumerateDevices().

After use, a MidiPort should be closed with the close() method.

MidiPort has an associated exception class, MidiPortException. An instance of MidiPortException is thrown when an error occurs.

See Also:

MidiPortException

MIDIPORT_INPUT

indicates the MIDI device is of type input.

MIDIPORT_OUTPUT

indicates the MIDI device is of type output.

MidiPort()

creates a MidiPort, but doesn't set the input and output devices.

MidiPort(int, int)

creates a MidiPort and sets the input and output device numbers.

close()

closes the current input and output devices.

enumerateDevices(int)

returns a Vector of devices of the specified type.

getDeviceName(int, int)

returns a String containing the system-defined name of a given MIDI device.

getDeviceNumber(int)

gets either the current inputDevice or current outputDevice.

getNumDevices(int)

returns the number of input or output devices known to the system.

messagesWaiting()

returns the number of complete messages received and not yet read with readMessage().

open()

opens the current input device for reading, and the current output device for writing.

readMessage(byte[], int)

reads a complete message, or as much will fit, into a user-specified buffer, if a message is waiting.

readMessage(MidiPortMessage)

reads a complete message, or as much will fit, and its timestamp into a MidiPortMsg object, if a message is waiting.

resetInput()

Re-enables MIDI input after an overrun has been detected.

setDeviceNumber(int, int)

sets either the inputDevice or outputDevice.

writeLongMessage(byte[], int, int)

writes a complete, or a portion of, a System Exclusive message to the output device.

writeShortMessage(byte, byte)

writes a 1-data-byte short message to the output device.

writeShortMessage(byte, byte, byte)

writes a 2-data-byte short message to the output device.

 public static final int MIDIPORT_INPUT

indicates the MIDI device is of type input.

 public static final int MIDIPORT_OUTPUT

indicates the MIDI device is of type output.

 public MidiPort()

creates a MidiPort, but doesn't set the input and output devices.

See Also:

setDeviceNumber, getDeviceNumber

 public MidiPort(int inputDeviceNumber,
                 int outputDeviceNumber) throws MidiPortException

creates a MidiPort and sets the input and output device numbers.

See Also:

setDeviceNumber, getDeviceNumber

 public void setDeviceNumber(int type,
                             int n) throws MidiPortException

sets either the inputDevice or outputDevice. A given system may have one or more MIDI devices accessible to the system. Before reading or writing MIDI data, the MidiPort must be opened on a specific input and output device. Devices are identified using an index; 0 is the lowest-numbered device. The number of valid input or output devices in the system can be derived from a call to the method getNumDevices(). The name of a given device can be derived from a call to the method getDeviceName(). A Vector of devices of a given type can be obtained through a call to the method enumerateDevices().

If the specified device is open when setDeviceNumber() is called, the system closes both input and output devices, and then opens the new devices.

If the device numbers were passed as arguments to the MidiPort constructor, you only need to call setDeviceNumber() if you want to change the device(s) being used.

Parameters:

type - either MIDIPORT_INPUT or MIDIPORT_OUTPUT

n - the number of the device.

Throws: MidiPortException

if type is not MIDIPORT_INPUT or MIDIPORT_OUTPUT, or if the MidiPort is already open and closing and reopening it throws an exception.

See Also:

getDeviceNumber, getNumDevices, getDeviceName

 public int getDeviceNumber(int type) throws MidiPortException

gets either the current inputDevice or current outputDevice. A given system may have one or more MIDI devices accessible to the system. Before reading or writing MIDI data, the MidiPort must be opened on a specific input and output device. Devices are identified using an index; 0 is the lowest-numbered device. The number of valid input or output devices in the system can be derived from a call to the method getNumDevices(). The name of a given device can be derived from a call to the method getDeviceName(). A Vector of devices of a given type can be obtained through a call to the method enumerateDevices().

Parameters:

type - either MIDIPORT_INPUT or MIDIPORT_OUTPUT.

Returns:

the selected device number.

Throws: MidiPortException

if type is neither MIDIPORT_INPUT nor MIDIPORT_OUTPUT.

See Also:

setDeviceNumber, getNumDevices, getDeviceName

 public static int getNumDevices(int type) throws MidiPortException

returns the number of input or output devices known to the system. A given system may have one or more accessible MIDI devices. Before reading or writing MIDI data, the MidiPort must be opened on a specific input and output device. Devices are identified using an index; 0 is the lowest-numbered device. The number of valid input or output devices in the system can be derived from a call to this method. The name of a given device can be derived from a call to the method getDeviceName().

Parameters:

type - either MIDIPORT_INPUT or MIDIPORT_OUTPUT.

Returns:

the number of devices of the selected type known to the system.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

See Also:

getDeviceName

 public static String getDeviceName(int type,
                                    int num) throws MidiPortException

returns a String containing the system-defined name of a given MIDI device.

Parameters:

type - either MIDIPORT_INPUT or MIDIPORT_OUTPUT.

num - the index of the device. 0 is the first device; use getNumDevices() to find out how many devices of the given type are known.

Returns:

the system-defined device name.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

See Also:

getNumDevices

 public static Vector enumerateDevices(int type) throws MidiPortException

returns a Vector of devices of the specified type.

Parameters:

type - either MIDIPORT_INPUT or MIDIPORT_OUTPUT.

Returns:

a Vector containing the names of all the known devices of the specified type.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

See Also:

getNumDevices, getDeviceName

 public void open() throws MidiPortException

opens the current input device for reading, and the current output device for writing.

Throws: MidiPortException

if the current input or output device has not been set, or if the device-dependent library flags an error. In the latter case, the message associated with the exception is derived from the system-dependent error.

See Also:

setDeviceNumber

 public void close() throws MidiPortException

closes the current input and output devices. If the MidiPort has not been opened, closing it does nothing.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

See Also:

open

 public void writeShortMessage(byte status,
                               byte data1,
                               byte data2) throws MidiPortException

writes a 2-data-byte short message to the output device. 2-byte messages include, for example, NoteOn and NoteOff. Note that the status byte must always be provided when writing messages; whether or not running status is used at lower levels is system-dependent. A one-byte version of writeShortMessage() is also defined.

Parameters:

status - the status byte containing the command and channel, as defined by the MIDI spec.

data1 - the first data byte following the status byte, as defined by the MIDI spec. For example, a NoteOn message has the note number as the first data byte.

data2 - the second data byte following the status byte, as defined by the MIDI spec. For example, a NoteOn message has the velocity as the second data byte.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

 public void writeShortMessage(byte status,
                               byte data1) throws MidiPortException

writes a 1-data-byte short message to the output device. 1-byte messages include, for example, Aftertouch. Note that the status byte must always be provided when writing messages; whether or not running status is used at lower levels is system-dependent. A two-byte version of writeShortMessage() is also defined.

Parameters:

status - the status byte containing the command and channel, as defined by the MIDI spec.

data1 - the data byte following the status byte, as defined by the MIDI spec. For example, an Aftertouch message has the pressure value as the data byte.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

 public void writeLongMessage(byte message[],
                              int len,
                              int timeout) throws MidiPortException

writes a complete, or a portion of, a System Exclusive message to the output device. This method blocks until the system has handled the message buffer array. On systems that support it, the timeout parameter can be used to abort a blocked transaction after a set period of time.

Parameters:

message - a byte buffer containing the message data. Both the sysex message start and message end bytes should be included. Other bytes should have their top bits clear, as per the MIDI spec.

len - the number of bytes in the message, including start and end bytes. If the buffer represents only part of a message, then len should be the length of the byte array.

timeout - the number of milliseconds to wait for the write to complete. On systems that support it, the call will abort after this time and throw an exception.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

 public int readMessage(byte message[],
                        int maxLength) throws MidiPortException

reads a complete message, or as much will fit, into a user-specified buffer, if a message is waiting. Use messagesWaiting() to determine if there is a message to be read. If the message is successfully read, the number of messages waiting returned by messagesWaiting() will be decremented. If the message won't fit completely in the message buffer you provide, the number of messages waiting won't be decremented.

If an input overrun has been detected (see messagesWaiting()), there may be spurious bytes in the input buffer. You should call resetInput() to restart MIDI input.

If there are no messages waiting, readMessage() does nothing.

Parameters:

message - a byte buffer into which the message is read by the system.

maxLength - the maximum number of bytes to write into the message buffer. This is normally just the length of the byte array.

Returns:

the number of bytes read into the message array.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

See Also:

messagesWaiting, resetInput

 public int readMessage(MidiPortMessage msg) throws MidiPortException

reads a complete message, or as much will fit, and its timestamp into a MidiPortMsg object, if a message is waiting. Use messagesWaiting() to determine if there is a message to be read. If the message is successfully read, the number of messages waiting returned by messagesWaiting() will be decremented. If the message won't fit completely in the message buffer you provide, the number of messages waiting won't be decremented.

If an input overrun has been detected (see messagesWaiting()), there may be spurious bytes in the input buffer. You should call resetInput() to restart MIDI input.

If there are no messages waiting, readMessage() does nothing.

Parameters:

message - a MidiPortMsg object.

Returns:

the number of bytes read into the message array.

Throws: MidiPortException

if the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

See Also:

readMessage, messagesWaiting, resetInput

 public int messagesWaiting() throws MidiPortException

returns the number of complete messages received and not yet read with readMessage(). Note that messagesWaiting() will not reflect that a long message has been partially received, or that a message has been partially read using readMessage().

This method is also used to check for input overrun. Overrun occurs when more data has been received but not read with readMessage() than can be stored in the system's circular buffer. When this happens, further input is not written to the circular buffer, and the next call to messagesWaiting() throws a "Buffer overrun" MidiPortException. Your program should check for this condition, and call resetInput() to re-enable MIDI input.

Throws: MidiPortException

if an input overrun condition has occurred, or if the device-dependent library flags an error. In the latter case, the message associated with the exception is derived from the system-dependent error.

See Also:

resetInput, readMessage

 public void resetInput() throws MidiPortException

Re-enables MIDI input after an overrun has been detected. Overrun occurs when more data has been received but not read with readMessage() than can be stored in the system's circular buffer. When this happens, further input is not written to the circular buffer, and the next call to messagesWaiting() throws a "Buffer overrun" MidiPortException. Your program should check for this condition, and call resetInput() to re-enable MIDI input.

Throws: MidiPortException

If the device-dependent library flags an error. The message associated with the exception is derived from the system-dependent error.

See Also:

messagesWaiting, readMessage

All Packages  Class Hierarchy  This Package  Previous  Next  Index