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

Setup and Generic Operations

midi_clear_queue()

SUMMARY	Clear data enqueued for input or output.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_clear_queue(midi_rx_t rx_port)

ARGUMENTS
rx_port:  MIDI receive or transmit port.

DESCRIPTION
The function midi_clear_queue() causes any pending output, or unreceived input, to be cleared from the driver.  It affects either the output queue or the input queue, depending on whether rx_port is the transmit port or the receive port.  (See midi_get_xmit() and midi_get_recv().)

RETURN
KERN_SUCCESS:  Queue cleared.

MIDI_BAD_PORT:  Rx_port was invalid.

midi_error(), midi_error_string()

SUMMARY	Print or return an error message as a string.

SYNOPSIS
#import <midi/midi_error.h>

void midi_error(const char *errorStr, kern_return_t errorCode)
const char *midi_error_string(kern_return_t errorCode)

ARGUMENTS
errorStr:  A string that you want displayed before the MIDI error string.

errorCode:  The error code to be interpreted.

DESCRIPTION
These utility functions help you interpret the return values of the other MIDI driver functions.  The function midi_error() displays a message on stderr.  The message contains a string you specify by errorStr, the string returned by midi_error_string(), and the actual error value (errorCode).

The function midi_error_string() returns the string associated with errorCode.

The error string is one of the following, as defined in <midi/midi_types.h>:

Code	String
MIDI_BAD_PARM	ªbad parameter list in messageº
MIDI_PORT_BUSY	ªaccess requested to existing exclusive access portº
MIDI_NOT_OWNER	ªownership rights requiredº
MIDI_NOTALIGNED	ªdata not properly alignedº
MIDI_NO_OWNER	ªno device ownerº
MIDI_MODE_WRONG	ªimproper operation in current modeº
MIDI_BAD_PORT	ªmessage received on wrong portº
MIDI_WILL_BLOCK	ªnext message will blockº

If the error code isn't one of the above, mach_error_string() is called.

midi_error_string() ® See midi_error()

midi_get_proto(), midi_set_proto()

SUMMARY	Get or set protocol parameters for MIDI input or output.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_get_proto(midi_rx_t rx_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_set_proto(midi_rx_t rx_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)

ARGUMENTS
rx_port:  MIDI receive or transmit port.

data_format:  The format for received data, one of MIDI_PROTO_RAW (the default), MIDI_PROTO_COOKED, or MIDI_PROTO_PACKED.

time_relative:  Whether timestamps are relative instead of absolute.  The default is NO.

clock_source:  The clock with which to synchronize.  This currently must be MIDI_PROTO_SYNC_SYS (the system clock).

inter_msg_quanta:  The number of quanta to wait for the next message to arrive (receive only).  The default is 1.

msg_frame_quanta:  The maximum number of quanta to wait from the first queued message before sending (receive only).  The default is 5.

queue_max:  number of messages (in all enqueued buffers) that can be enqueued without causing send to block (transmit only).  The default is 8000.

DESCRIPTION
The function midi_set_proto() specifies protocol attributes of the MIDI driver for the direction (receive or transmit) specified by rx_port.  If rx_port is the receive port, the data_format parameter specifies in what format the data is to be forwarded to the application.  The time_relative parameter specifies whether time-tags are relative to the previous event (YES), or represent the absolute time as maintained by the timer service (NO).  The clock_source parameter specifies where the device's implemented timer service is to obtain its time base.  The intended possibilities are the system clock, MIDI clock, or MIDI Time Code, but only the first of these is currently implemented.  

The inter_msg_quanta parameter specifies the number of quanta that need to elapse between received MIDI messages before the received data will be forwarded to the application.  When a message is received, an internal driver timer is set for inter_msg_quanta quanta in the future.  Any message arriving before this time expires  causes 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 application.  Using the two parameters, you can tune the driver to deliver data in convenient packets.  For example, a packet might consist of events that occur in rapid succession, such as the notes of a chord.  By grouping data into packets, you can reduce the overhead involved in sending messages from the driver to the application.  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.

The function midi_get_proto() returns data previously set using the midi_set_proto() call, or the default information if midi_set_proto() hasn't been called.  Note that the arguments to midi_get_proto() are pointers; the parameters are returned by reference.

EXAMPLE
port_t         rx_port;
kern_return_t  error;

error = midi_set_proto(
            rx_port,               // receive or transmit port
            MIDI_PROTO_COOKED      // cooked data input
            FALSE,                 // absolute time
            MIDI_PROTO_SYNC_SYS,   // system derived clock
            1,                     // 1 ms (quanta) between msgs
            10,                    // 10 ms (quanta) max from 1st msg
            512);                  // 512 msgs queued for output max
if (error != KERN_SUCCESS) {
    midi_error("midi_set_proto returned value of ", error);
    exit(1);
}

RETURN
KERN_SUCCESS:  Protocol set.

MIDI_BAD_PORT:  Rx_port was invalid.

MIDI_UNSUP:  Operation not supported.

midi_get_recv(), midi_get_xmit()

SUMMARY	Get port for receiving or transmitting MIDI data.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_get_recv(midi_dev_t device_port, port_t owner_port, port_t *recv_port)
kern_return_t midi_get_xmit(midi_dev_t device_port, port_t owner_port, port_t *xmt_port)

ARGUMENTS
device_port:  The MIDI device port.

owner_port:  The port registered as the owner port.

recv_port:  Pointer to the port to use for MIDI receive requests.

xmit_port:  Pointer to the port to use for MIDI output requests.

DESCRIPTION
The function midi_get_recv() obtains a pointer to the receive MIDI port, which is used for all activities relating to MIDI data reception.  Similarly, midi_get_xmit() obtains a pointer to the transmit port 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 receive or transmit port is returned by reference in the parameter recv_port or xmit_port, respectively.

RETURN
KERN_SUCCESS:  Port was obtained.

MIDI_BAD_PORT:  device_port is invalid.

MIDI_NOT_OWNER:  owner_port is not the registered owner port.

midi_get_xmit() ® See midi_get_recv()

midi_set_owner()

SUMMARY	Acquire ownership of a MIDI device.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_set_owner(midi_dev_t device_port, port_t owner_port, port_t *negotiation_port)

ARGUMENTS
device_port:  The MIDI device that is to be acquired (retrieved from netname_look_up()).

owner_port:  The port to register as the owner port.

negotiation_port:  A pointer to the port to register as the target for access requests by non-owners.  On failure to acquire ownership, the current negotiation port is returned by reference in this parameter.

DESCRIPTION
The function 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 network name server (see the NeXT Operating System Software 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 intended to specify a port for negotiating access to the device when it is already busy.  However, a negotiation protocol hasn't yet been defined, so currently this parameter isn't useful.  

EXAMPLE
port_t         device_port, owner_port, negotiation_port;
kern_return_t  error;

error = midi_set_owner(device_port, owner_port, &negotiation_port);
if (error != KERN_SUCCESS) {
    midi_error("midi_set_owner returned value of ", error);
    exit(1);
}

RETURN
KERN_SUCCESS:  Ownership has been acquired.

MIDI_BAD_PORT:  device_port or owner_port was invalid.

MIDI_PORT_BUSY:  The MIDI device is already owned; negotiation_port contains port to current owner.

midi_set_proto() ® See midi_get_proto()