Release 2.0  Copyright ã1991 by NeXT Computer, Inc.  All Rights Reserved.

Receiving and Transmitting MIDI Data

midi_get_data()

SUMMARY	Get received MIDI data.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_get_data(midi_rx_t receive_port, port_ t reply_port)

ARGUMENTS
receive_port:  The MIDI receive port.

reply_port:  Port to send MIDI data to.

DESCRIPTION
The function 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 application as either raw, cooked, or packed data, according to the input protocol specified (see midi_set_proto()).  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 the messages midi_ret_raw_data, midi_ret_cooked_data, or midi_ret_packed_data will be sent on the port specified by the reply_port parameter (see midi_reply_handler()).

RETURN
KERN_SUCCESS:  Data enqueued for output.

MIDI_BAD_PORT:  Receive_port was invalid.

midi_get_sys_ignores(), midi_set_sys_ignores()

SUMMARY	Set or get the bitmap specifying MIDI system commands to be ignored.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_get_sys_ignores(midi_rx_t receive_port, u_int *sys_ignores)
kern_return_t midi_set_sys_ignores(midi_rx_t receive_port, u_int sys_ignores)

ARGUMENTS
receive_port:  The MIDI receive port.

sys_ignores:  Bitmap (or a pointer to it) describing which MIDI system commands to ignore.

DESCRIPTION
The function midi_set_sys_ignores() specifies which MIDI system commands will be ignored by the device driver.  If any one of these commands is subsequently received, it is discarded along with all data associated with it.  The sys_ignores parameter is a bitmap specifying which MIDI system commands are to be ignored.  See <midi/midi_types.h> for defines for the bits associated with each MIDI system command; a number of constants of the form MIDI_IGNORE_systemMsg are provided.

The function midi_get_sys_ignores() returns the sys_ignores bitmap by reference.

RETURN
KERN_SUCCESS:  Data enqueued for output.

MIDI_BAD_PORT:  Receive_port was invalid.

midi_output_queue_notify()

SUMMARY	Ask to be notified when queue gets small enough.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_output_queue_notify(midi_dev_t device_port, port_t owner_port, port_t reply_port, u_int queue_size)

ARGUMENTS
device_port:  The MIDI device port.

owner_port:  The port registered as the owner port.

reply_port:  The port to send a midi_queue_notify() message on.

queue_size:  The maximum number of messages that can be enqueued before a reply is sent.

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

RETURN
KERN_SUCCESS:  A midi_queue_notify() message will be returned.

MIDI_BAD_PORT:  device_port was invalid.

MIDI_NOT_OWNER:  owner_port is not the registered owner port.

midi_output_queue_size()

SUMMARY	Find out the current and maximum sizes of the MIDI output queue.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_output_queue_size(midi_dev_t device_port, u_int *queue_size, u_int *queue_max)

ARGUMENTS
device_port:  The MIDI device port.

queue_size:  Pointer to the current number of MIDI messages enqueued for output.

queue_max:  Pointer to the maximum number of MIDI messages that may be enqueued for output without causing the driver to block.

DESCRIPTION
The function midi_output_queue_size() returns a pointer to the number of messages enqueued for output, and a pointer to the maximum number of messages that may be enqueued for output before the device stops receiving any further messages on its transmit port.

RETURN
KERN_SUCCESS:  Output queue current and maximum size was returned.

MIDI_BAD_PORT:  device_port was invalid.

MIDI_NOT_OWNER:  owner_port is not the registered owner port.

midi_send_cooked_data(), midi_send_packed_data(), midi_send_raw_data()

SUMMARY	Enqueue MIDI data for output.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_send_cooked_data(midi_rx_t xmit_port, midi_cooked_t midi_cooked_data, u_int count, boolean_t dont_block)
kern_return_t midi_send_packed_data(midi_rx_t xmit_port, u_int quanta, midi_packed_t midi_packed_data, u_int count, boolean_t dont_block)
kern_return_t midi_send_raw_data(midi_rx_t xmit_port, midi_raw_t midi_raw_data, u_int count, boolean_t dont_block)

ARGUMENTS
xmit_port:  The MIDI transmit port.

midi_cooked_data:  An array of cooked MIDI events.

midi_packed_data:  An array of packed MIDI events.

midi_raw_data:  An array of raw MIDI events.

count:  The number of MIDI events in the array.

dont_block:  Whether to cause a warning to be returned if the queue is full.

DESCRIPTION
The functions midi_send_cooked_data(), midi_send_packed_data(), and midi_send_raw_data() cause an array of bytes to be enqueued for output.  The bytes consist of MIDI messages in the cooked, packed, or raw format, respectively.  The xmit_port parameter is the port previously obtained using the midi_get_xmit() call on the device port.  The parameter midi_packed_data, midi_raw_data, or midi_cooked_data is an array of elements of the respective type (see <midi/midi_types.h>).  In the packed format, each element consists of a single byte of data; in the raw format, each element contains a quanta timestamp and a single byte of data; and in the cooked format, each element contains a quanta timestamp, a byte count, and three bytes of data.  The timestamp in the raw and cooked formats 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_get_out_timer_port() and midi_set_proto()).  

If dont_block is YES, the function will return the error value MIDI_WILL_BLOCK if this request to send data would cause the number of messages enqueued for output to equal or exceed the maximum allowed queue size.  If dont_block is NO, the next attempt to enqueue output data may block until the queue has shrunk below the maximum size.  Along with midi_output_queue_notify(), the dont_block parameter can be used to flow-control output to the device.

RETURN
KERN_SUCCESS:  Data enqueued for output.

MIDI_BAD_PORT:  xmit_port was invalid.

MIDI_WILL_BLOCK:  The next call enqueuing output data may be delayed (queue full).

midi_send_packed_data() ® See midi_send_cooked_data()

midi_send_raw_data() ® See midi_send_cooked_data()

midi_set_sys_ignores() ® See midi_get_sys_ignores()