MIDI(4) — UNIX Programmer’s Manual

NAME

midi_set_owner, midi_get_xmit, midi_get_recv, midi_get_out_timer_port, midi_set_quanta_per_clock, midi_get_quanta_per_clock, midi_output_queue_size, midi_output_queue_notify, midi_send_raw_data, midi_send_cooked_data, midi_send_packed_data, midi_get_data, midi_set_sys_ignores, midi_get_sys_ignores, midi_set_in_timer_port, midi_get_in_timer_port, midi_set_proto, midi_get_proto, midi_clear_queue, midi_reply_handler, midi_error, midi_error_string − MIDI device interface

SYNOPSIS

#include <midi/midi_server.h>
#include <midi/midi_reply_handler.h>
#include <midi/midi_error.h>
kern_return_t midi_set_owner (
midi_dev_tdevice_port,
port_towner_port,
port_t ∗negotiation_port)
kern_return_t midi_get_xmit (
midi_dev_tdevice_port,
port_towner_port,
port_t ∗xmit_port)
kern_return_t midi_get_recv (
midi_dev_tdevice_port,
port_towner_port,
port_t ∗recv_port)
kern_return_t midi_get_out_timer_port (
midi_dev_tdevice_port,
port_t ∗timer_port)
kern_return_t midi_set_quanta_per_clock (
midi_dev_tdevice_port,
port_towner_port,
intquanta_per_clock)
kern_return_t midi_get_quanta_per_clock (
midi_dev_tdevice_port,
port_towner_port,
int ∗quanta_per_clock)
kern_return_t midi_output_queue_size (
midi_dev_tdevice_port,
u_int ∗queue_size,
u_int ∗queue_max)
kern_return_t midi_output_queue_notify (
midi_dev_tdevice_port,
port_towner_port,
port_treply_port,
u_intqueue_size)
kern_return_t midi_send_raw_data (
midi_rx_txmit_port,
midi_raw_tmidi_raw_data,
u_intmidi_raw_dataCnt,
boolean_tdont_block)
kern_return_t midi_send_cooked_data (
midi_rx_txmit_port,
midi_cooked_tmidi_cooked_data,
u_intmidi_cooked_dataCnt,
boolean_tdont_block)
kern_return_t midi_send_packed_data (
midi_rx_txmit_port,
u_intquanta,
midi_packed_tmidi_packed_data,
u_intmidi_packed_dataCnt,
boolean_tdont_block)
kern_return_t midi_get_data(
midi_rx_treceive_port,
port_treply_port)
kern_return_t midi_set_sys_ignores (
midi_rx_treceive_port,
u_intsys_ignores)
kern_return_t midi_get_sys_ignores (
midi_rx_treceive_port,
u_int ∗sys_ignores)
kern_return_t midi_set_in_timer_port (
midi_rx_trx_port,
port_ttimer_port)
kern_return_t midi_get_in_timer_port (
midi_rx_trx_port,
port_t ∗timer_port)
kern_return_t midi_set_proto (
midi_rx_trx_port,
u_intdata_format,
boolean_ttime_relative,
u_intclock_source,
u_intinter_msg_quanta,
u_intmsg_frame_quanta,
u_intqueue_max)
kern_return_t midi_get_proto (
midi_rx_trx_port,
u_int ∗data_format,
boolean_t ∗time_relative,
u_int ∗clock_source,
u_int ∗inter_msg_quanta,
u_int ∗msg_frame_quanta,
u_int ∗queue_max)
kern_return_t midi_clear_queue(midi_rx_t rx_port)
kern_return_t midi_reply_handler (
msg_header_t ∗msg,
midi_reply_t ∗midi_reply)
void midi_error(const char ∗ s, kern_return_t r)
const char ∗midi_error_string(kern_return_t r)

DESCRIPTION

The Musical Instrument Digital Interface (MIDI) driver implements a protocol for communicating with Musical Instruments using the 1.0 specification of the MIDI standard developed jointly by the MIDI Manufacturers Association (MMA) and the Japan MIDI Standards Committee (JMSC).

The MIDI driver is divided into two parts: those routines providing access to MIDI data transmission and reception, and routines controlling the timing of MIDI events. For a description of the later, see midi_timer(4). For more general documentation on MIDI programming see The NeXT System Reference Manual.

Midi_set_owner establishes ownership of one of the two MIDI devices. The device_port parameter is obtained by looking up either midi0 or midi1 from the netname server (see the documentation for netname in The NeXT System Reference Manual). The owner_port parameter is a port to be registered as the owner of this device. When the registered owner_port is deallocated the device is released. The negotiation_port parameter is used to specify a port to be used for negotiating access to the device. If midi_set_owner is successful, the port referenced by negotiation_port is registered with the driver to be returned when ownership is requested for a device which is already owned. Thus, if the call fails, a port will be returned in negotiation_port that can be used to gain further access to the driver.

Midi_get_xmit obtains the transmit MIDI port. This port is used for all activities relating to MIDI output. In addition to the device_port parameter, a valid owner_port establishes that you have the right to obtain this port. The transmit port is returned in the xmit_port parameter.

As with midi_get_xmit, midi_get_recv returns the MIDI receive port in the recv_port parameter.

Midi_get_out_timer_port returns the timer port implemented by this MIDI device. The device may actually be using some other timer service. By default, the timer used for both transmit and receive (see midi_set_in_timer_port) is the driver’s timer port, but any port providing the same services may, in fact, be used by the device. The ownership port is not required to obtain this port as it cannot be used to control MIDI itself. It may be useful for other applications to synchronize themselves to MIDI input or output by using the same clock that is used by the device itself. See midi_timer(4) for more information on using timer services.

Midi_set_quanta_per_clock is used when the MIDI timer is synchronized to MIDI Clock messages. A quantum is the basic unit of scheduling in the MIDI device. The number of quanta per microsecond is specified using the timer_set_quantum call on the timer port being used by this device (see midi_timer(4)). In the case of MIDI Clock synchronization the timespan that each Clock message represents must be specified using this call.

Midi_get_quanta_per_clock returns the value previously set by midi_set_quanta_per_clock, or the default value if none has been set.

Midi_output_queue_size returns both the number of messages enqueued for output and the maximum number of messages that may be enqueued for output before the device stops receiving messages on its transmit port.

Midi_output_queue_notify registers reply_port as the port to send a midi_queue_notify message on (see midi_reply_handler below) when the size of the output becomes less than or equal to queue_size messages in length. This call can be used to flow-control MIDI output.

Midi_send_raw_data causes an array of time−tagged bytes to be enqueued for output. The xmit_port parameter is the port previously obtained using the midi_get_xmit call on the device port. Midi_raw_data is an array of midi_raw_data_t elements (see <midi/midi_types.h>). Each element contains a quanta timestamp and a single byte of data. The timestamp represents either a relative delay from the previous MIDI output event, or an absolute time as represented by the timer service associated with the output MIDI device (see midi_set_in_timer_port and midi_set_proto below). The dont_block parameter causes the driver to return the error value MIDI_WILL_BLOCK if this message will cause the number of messages enqueued for output to equal or exceed the maximum queue size. The error retrun indicates that the next attempt to enqueue output data may result in the next call to enqueue output data blocking until the queue has fallen below the maximum allowed queue_size. The data will be enqueued for output. This, along with the midi_output_queue_notify call can be used to flow−control output to the device.

Midi_send_cooked_data causes an array of time−tagged MIDI messages to be enqueued for output. Midi_cooked_data is an array of midi_cooked_data_t elements (see <midi/midi_types.h>). Each element contains a quanta timestamp, a byte count and from one to three bytes of data. The dont_block parameter behaves as in midi_send_raw_data, above.

Midi_send_packed_data causes an array of bytes to be enqueued for output. The quanta parameter specifies when the data should start to be sent. Midi_packed_data is an array of midi_packed_data_t elements (see <midi/midi_types.h>). Each element contains a byte of data. The dont_block parameter behaves as in midi_send_raw_data, above.

Midi_get_data causes any received data to be sent to the specified port. The receive_port parameter is the port previously obtained using the midi_get_recv call on the device port. When data has been received it will be forwarded to the user as either raw, cooked, or packed data, according to the input protocol specified (see midi_set_proto below). The exception is that if a System Exclusive message is received while in cooked mode, the data will be sent as packed data. The appropriate one of midi_ret_raw_data, midi_ret_cooked_data, or midi_ret_packed_data messages will be sent on the port specified by the reply_port parameter (see midi_reply_handler below).

Midi_set_sys_ignores sets the set of MIDI system messages that will be ignored by the device driver. If any one of these messages is received and has been specified to be ignored it, and all data associated with it, are discarded. The sys_ignores parameter is a bit−map specifying which MIDI system messages are to be ignored (see <midi/midi_types.h> for defines for the bits associated with each MIDI system message).

Midi_get_sys_ignores returns a bit−map of those MIDI system messages being ignored by the driver.

Midi_set_in_timer_port specifies the timer service to be used in timing events one either the input or output sides of the device. The rx_port parameter is either the receive or transmit port, depending on which direction is to be set. The default timer used is the timer implemented by the device itself (see midi_get_out_timer_port, above and midi_timer(4)).

Midi_get_in_timer_port returns the port representing the timer that is being used by this direction of the MIDI device.

Midi_set_proto specifies protocol attributes of the specified direction of the MIDI driver. The data_format parameter specifies how data received (for the receive side of the driver) is to be returned to the user. It can be set to one of MIDI_PROTO_RAW, MIDI_PROTO_COOKED, or MIDI_PROTO_PACKED. The time_relative parameter specifies whether time−tags on either output, or as returned on input, are relative to the previous event, or represent the absolute time as maintained by the connected timer service. The clock_source parameter specifies where the device’s implemented timer service is to obtain its time−base. It can be one of MIDI_PROTO_SYNC_SYS, to synchronize off of the system clock, MIDI_PROTO_SYNC_CLOCK, to synchronize off of received MIDI Clock messages, or MIDI_PROTO_SYNC_MTC, to synchronize off of received MIDI Time Code messages. The inter_msg_quanta parameter specifies the number of quanta that need to elapse between received MIDI messages before received data will be forwarded to the user. When a message is received an internal driver timer will be set for inter_msg_quanta quanta in the future. A message arriving before this the timer expires will cause the timer to be restarted. The msg_frame_quanta parameter specifies the maximum amount of time that can elapse from receipt of the first message before the received data is forwarded to the user. Using the two parameters users can tune the driver to deliver data in convenient packets that (may) relate to events that are close together in time (such as chords). It can also reduce the overhead involved in sending messages from the driver to the user. The queue_max parameter specifies the maximum number of messages that can be enqueued for output before the driver stops listening for output data messages.

Midi_get_proto returns data previously set using the midi_set_proto call, or the default information of no parameters have been set.

Midi_clear_queue causes any pending output, or unreceived input, to be cleared from the driver.

Certain calls on the MIDI driver may result in messages being sent asynchronously back to the calling application (actually, to the port that was registered in the call resulting in the asynchronous event). The routine midi_reply_handler takes the received message (resulting from a msg_receive; see the section on Mach programming in The NeXT System Reference Manual), and a pointer to a midi_reply_t structure (see <midi/midi_reply_handler.h>). The maximum size message that the MIDI driver may send asynchronously is MIDI_REPLY_INMSG_SIZE. The structure referenced by midi_reply contains pointers to (user supplied) routines that will be called when the corresponding message is received. It also contains a void ∗ argument that is passed as the first parameter to each user−supplied routine. If no routine is specified (value of the structure member is zero) the message is thrown away. The routines that the user must implement are as follows:

kern_return_t (∗ret_raw_data) (
void ∗arg,
midi_raw_tmidi_raw_data,
u_intmidi_raw_dataCnt);
kern_return_t (∗ret_cooked_data) (
void ∗arg,
midi_cooked_tmidi_cooked_data,
u_intmidi_cooked_dataCnt);
kern_return_t (∗ret_packed_data) (
void ∗arg,
u_intquanta,
midi_packed_tmidi_packed_data,
u_intmidi_packed_dataCnt);
kern_return_t (∗queue_notify) (
void ∗arg,
u_intqueue_size);

Midi_error prints an error message on stderr corresponding to the return value specified in the r parameter (see mach_error (3)). The error must be one returned by one of the above listed routines for the proper error message to be printed.

Midi_error_string returns the error string associated with the specified error as would be used by midi_error.

ERRORS

Each function returns KERN_SUCCESS unless there’s an error, in which case one of the following values is returned:

MIDI_BAD_PARM
A parameter passed to this routine was invalid.

MIDI_PORT_BUSY
The device is already owned, the current owner’s negotiation_port is returned.

MIDI_NOT_OWNER
The port passed as the owner_port was not the same as the registered owner.

MIDI_NOTALIGNED
Data passed into the device was not properly aligned.

MIDI_NO_OWNER
The device must be owned to proceed with this operation. No owner is currently registered.

MIDI_MODE_WRONG
The operating mode of the device is inconsistant with the request.

MIDI_BAD_PORT
The destination port used does not implement the requested routine.

MIDI_WILL_BLOCK
This is not a failure, rather a warning that the next such operation may not return immediately.

MIDI_UNSUP
The requested operation is not supported by the driver at this time.

NOTES

For this release the only valid clock_source that can be specified is MIDI_PROTO_SYNC_SYS. Also, inter_msg_quanta and msg_frame_quanta are ignored by the driver. Data is forwarded as soon as it is received.

FILES

/usr/lib/kern_loader/Midi/midi_reloc,
/usr/lib/kern_loader/Midi/midi.kern_loader

Museum

Related Articles