All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class jmidi.MidiPort

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

public class MidiPort
extends Object
A class for platform-independent MIDI input and output.

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

Variable Index

 o MIDIPORT_INPUT
indicates the MIDI device is of type input.
 o MIDIPORT_OUTPUT
indicates the MIDI device is of type output.

Constructor Index

 o MidiPort()
creates a MidiPort, but doesn't set the input and output devices.
 o MidiPort(int, int)
creates a MidiPort and sets the input and output device numbers.

Method Index

 o close()
closes the current input and output devices.
 o enumerateDevices(int)
returns a Vector of devices of the specified type.
 o getDeviceName(int, int)
returns a String containing the system-defined name of a given MIDI device.
 o getDeviceNumber(int)
gets either the current inputDevice or current outputDevice.
 o getNumDevices(int)
returns the number of input or output devices known to the system.
 o messagesWaiting()
returns the number of complete messages received and not yet read with readMessage().
 o open()
opens the current input device for reading, and the current output device for writing.
 o readMessage(byte[], int)
reads a complete message, or as much will fit, into a user-specified buffer, if a message is waiting.
 o readMessage(MidiPortMessage)
reads a complete message, or as much will fit, and its timestamp into a MidiPortMsg object, if a message is waiting.
 o resetInput()
Re-enables MIDI input after an overrun has been detected.
 o setDeviceNumber(int, int)
sets either the inputDevice or outputDevice.
 o writeLongMessage(byte[], int, int)
writes a complete, or a portion of, a System Exclusive message to the output device.
 o writeShortMessage(byte, byte)
writes a 1-data-byte short message to the output device.
 o writeShortMessage(byte, byte, byte)
writes a 2-data-byte short message to the output device.

Variables

 o MIDIPORT_INPUT
 public static final int MIDIPORT_INPUT
indicates the MIDI device is of type input.

 o MIDIPORT_OUTPUT
 public static final int MIDIPORT_OUTPUT
indicates the MIDI device is of type output.

Constructors

 o MidiPort
 public MidiPort()
creates a MidiPort, but doesn't set the input and output devices.

See Also:
setDeviceNumber, getDeviceNumber
 o MidiPort
 public MidiPort(int inputDeviceNumber,
                 int outputDeviceNumber) throws MidiPortException
creates a MidiPort and sets the input and output device numbers.

See Also:
setDeviceNumber, getDeviceNumber

Methods

 o setDeviceNumber
 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
 o getDeviceNumber
 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
 o getNumDevices
 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
 o 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
 o enumerateDevices
 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
 o open
 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
 o close
 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
 o writeShortMessage
 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.
 o writeShortMessage
 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.
 o writeLongMessage
 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.
 o readMessage
 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
 o readMessage
 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
 o messagesWaiting
 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
 o resetInput
 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