This is Setup.rtf in view mode; [Download] [Up]
paperh22175 margl-907 margr0 margt0 margb0 {fonttblf0fswiss Helvetica;f1froman Times;f2fmodern Courier;f3ftech Symbol;f4froman Palantino;}fi0 ri0 ql sb0 f1 fs24 Release 2.0 Copyright f3 'e3f1 1991 by NeXT Computer, Inc. All Rights Reserved.
b fs36 f1 ql ri1007 li1108 fi-503 Setup and Generic Operations
fs16
fs36 pard s28 li1108 fi0 ri1007 ql fs16
fs36 midi_clear_queue()
fs16
fs36 pard s20 li4636 fi-2520 ri1007 ql tx4636 b0 fs28 fs16
fs28 SUMMARY Clear data enqueued for input or output.
fs16
fs28 pard s29 li2116 fi0 ri1007 ql fs16 fs28 SYNOPSIS
pard s5 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b #import <midi/midi_server.h>
fs16
fs28 pard s11 li3124 fi-503 ri1007 ql b0 kern_return_t b midi_clear_queue(b0 midi_rx_t i rx_portb i0 )
s9 li2116 fi503 fi0 b0 fs16
fs28 ARGUMENTS
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 i rx_porti0 : MIDI receive or transmit port.
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 DESCRIPTION
pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 The functionb midi_clear_queue()b0 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 i rx_porti0 is the transmit port or the receive port. (See b midi_get_xmit() b0 andb midi_get_recv()b0 .)
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 RETURN
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 KERN_SUCCESS: Queue cleared.
fs16
fs28 MIDI_BAD_PORT: i Rx_porti0 was invalid.
fs16
fs28 pard s28 li1108 fi0 ri1007 ql b fs36 fs16
fs36 midi_error(), midi_error_string()
fs16
fs36 pard s20 li4636 fi-2520 ri1007 ql tx4636 b0 fs28 fs16
fs28 SUMMARY Print or return an error message as a string.
fs16
fs28 pard s29 li2116 fi0 ri1007 ql fs16 fs28 SYNOPSIS
pard s5 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b #import <midi/midi_error.h>
fs16
fs28 pard s11 li3124 fi-503 ri1007 ql b0 voidb midi_error(b0 const char i *errorStri0 , kern_return_tb b0 i errorCodeb i0 )
b0 const char *b midi_error_string(b0 kern_return_tb b0 i errorCodeb i0 )
s9 li2116 fi503 fi0 b0 fs16
fs28 ARGUMENTS
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 i errorStri0 : A string that you want displayed before the MIDI error string.
fs16
fs28 i errorCodei0 : The error code to be interpreted.
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 DESCRIPTION
pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 These utility functions help you interpret the return values of the other MIDI driver functions. The function b midi_error()b0 displays a message on b stderrb0 . The message contains a string you specify by i errorStri0 , the string returned by b midi_error_string()b0 , and the actual error value (i errorCodei0 ).
fs16
fs28 The functionb midi_error_string()b0 returns the string associated with i errorCodei0 .
fs16
fs28 The error string is one of the following, as defined in b <midi/midi_types.h>b0 :
fs16
fs28 pard s31 li3124 fi0 ri1007 ql b tx6652 tx8668 tx10684 fs16 fs28 Code String
s21 b0 tx6652 tx8668 tx10684 MIDI_BAD_PARM 'aabad parameter list in message'ba
fi0 MIDI_PORT_BUSY 'aaaccess requested to existing exclusive access port'ba
fi0 MIDI_NOT_OWNER 'aaownership rights required'ba
fi0 MIDI_NOTALIGNED 'aadata not properly aligned'ba
fi0 MIDI_NO_OWNER 'aano device owner'ba
fi0 MIDI_MODE_WRONG 'aaimproper operation in current mode'ba
fi0 MIDI_BAD_PORT 'aamessage received on wrong port'ba
fi0 MIDI_WILL_BLOCK 'aanext message will block'ba
fs16
fs28 pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 If the error code isn'27t one of the above, b mach_error_string() b0 is called.
fs16
fs28 pard s28 li1108 fi0 ri1007 ql b fs36 fs16
fs36 midi_error_string() f3 b0 'aef1 b See midi_error()
fs16
fs36 fs16
fs36 midi_get_proto(), midi_set_proto()
fs16
fs36 pard s20 li4636 fi-2520 ri1007 ql tx4636 b0 fs28 fs16
fs28 SUMMARY Get or set protocol parameters for MIDI input or output.
fs16
fs28 pard s29 li2116 fi0 ri1007 ql fs16 fs28 SYNOPSIS
pard s5 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b #import <midi/midi_server.h>
fs16
fs28 pard s11 li3124 fi-503 ri1007 ql b0 kern_return_t b midi_get_proto(b0 midi_rx_t i rx_porti0 , u_int *i data_formati0 , boolean_t *i time_relativei0 , u_int *i clock_sourcei0 , u_int *i inter_msg_quantai0 , u_int *i msg_frame_quantai0 , u_int *i queue_maxb i0 )
b0 kern_return_t b midi_set_proto(b0 midi_rx_t i rx_porti0 , u_int i data_formati0 , boolean_t i time_relativei0 , u_int i clock_sourcei0 , u_int i inter_msg_quantai0 , u_int i msg_frame_quantai0 , u_int i queue_maxb i0 )
s9 li2116 fi503 fi0 b0 fs16
fs28 ARGUMENTS
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 i rx_porti0 : MIDI receive or transmit port.
fs16
fs28 i data_formati0 : The format for received data, one of MIDI_PROTO_RAW (the default), MIDI_PROTO_COOKED, or MIDI_PROTO_PACKED.
fs16
fs28 i time_relativei0 : Whether timestamps are relative instead of absolute. The default is NO.
fs16
fs28 i clock_sourcei0 : The clock with which to synchronize. This currently must be MIDI_PROTO_SYNC_SYS (the system clock).
fs16
fs28 i inter_msg_quantai0 : The number of quanta to wait for the next message to arrive (receive only). The default is 1.
fs16
fs28 i msg_frame_quantai0 : The maximum number of quanta to wait from the first queued message before sending (receive only). The default is 5.
fs16
fs28 i queue_maxi0 : number of messages (in all enqueued buffers) that can be enqueued without causing send to block (transmit only). The default is 8000.
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 DESCRIPTION
pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 The functionb midi_set_proto()b0 specifies protocol attributes of the MIDI driver for the direction (receive or transmit) specified by i rx_porti0 . If i rx_porti0 is the receive port, the i data_formati0 parameter specifies in what format the data is to be forwarded to the application. The i time_relativei0 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 i clock_sourcei0 parameter specifies where the device'27s 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.
fs16
fs28 The i inter_msg_quantai0 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 i inter_msg_quantai0 quanta in the future. Any message arriving before this time expires causes the timer to be restarted. The i msg_frame_quantai0 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 i queue_maxi0 parameter specifies the maximum number of messages that can be enqueued for output before the driver stops listening for output data messages.
fs16
fs28 The functionb midi_get_proto()b0 returns data previously set using the b midi_set_proto()b0 call, or the default information if b midi_set_proto()b0 hasn'27t been called. Note that the arguments to b midi_get_proto()b0 are pointers; the parameters are returned by reference.
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 EXAMPLE
s16 li2620 fi-503 fi0 f2 fs24 port_t rx_port;
fi0 kern_return_t error;
fi0
fi0 error = midi_set_proto(
fi0 rx_port, // receive or transmit port
fi0 MIDI_PROTO_COOKED // cooked data input
fi0 FALSE, // absolute time
fi0 MIDI_PROTO_SYNC_SYS, // system derived clock
fi0 1, // 1 ms (quanta) between msgs
fi0 10, // 10 ms (quanta) max from 1st msg
fi0 512); // 512 msgs queued for output max
fi0 if (error != KERN_SUCCESS) {
fi0 midi_error("midi_set_proto returned value of ", error);
fi0 exit(1);
fi0 }
s9 li2116 fi0 f1 fs28 fs16
fs28 RETURN
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 KERN_SUCCESS: Protocol set.
fs16
fs28 MIDI_BAD_PORT: i Rx_porti0 was invalid.
fs16
fs28 MIDI_UNSUP: Operation not supported.
fs16
fs28 pard s28 li1108 fi0 ri1007 ql b fs36 fs16
fs36 midi_get_recv(), midi_get_xmit()
fs16
fs36 pard s20 li4636 fi-2520 ri1007 ql tx4636 b0 fs28 fs16
fs28 SUMMARY Get port for receiving or transmitting MIDI data.
fs16
fs28 pard s29 li2116 fi0 ri1007 ql fs16 fs28 SYNOPSIS
pard s5 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b #import <midi/midi_server.h>
fs16
fs28 pard s11 li3124 fi-503 ri1007 ql b0 kern_return_t b midi_get_recv(b0 midi_dev_t i device_porti0 , port_t i owner_porti0 , port_t *i recv_portb i0 )
b0 kern_return_t b midi_get_xmit(b0 midi_dev_t i device_porti0 , port_t i owner_porti0 , port_t *i xmt_portb i0 )
s9 li2116 fi503 fi0 b0 fs16
fs28 ARGUMENTS
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 i device_porti0 : The MIDI device port.
fs16
fs28 i owner_porti0 : The port registered as the owner port.
fs16
fs28 i recv_porti0 : Pointer to the port to use for MIDI receive requests.
fs16
fs28 i xmit_porti0 : Pointer to the port to use for MIDI output requests.
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 DESCRIPTION
pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 The functionb midi_get_recv()b0 obtains a pointer to the receive MIDI port, which is used for all activities relating to MIDI data reception. Similarly, b midi_get_xmit()b0 obtains a pointer to the transmit port used for all activities relating to MIDI output. In addition to the i device_porti0 parameter, a valid i owner_porti0 establishes that you have the right to obtain this port. The receive or transmit port is returned by reference in the parameteri recv_porti0 or i xmit_porti0 , respectively.
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 RETURN
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 KERN_SUCCESS: Port was obtained.
fs16
fs28 MIDI_BAD_PORT: i device_porti0 is invalid.
fs16
fs28 MIDI_NOT_OWNER: i owner_porti0 is not the registered owner port.
fs16
fs28 pard s28 li1108 fi0 ri1007 ql b fs36 fs16
fs36 midi_get_xmit() f3 b0 'aef1 b See midi_get_recv()
fs16
fs36 pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 b0 fs28
fs16
fs28 pard s6 li1108 fi0 ri1007 ql b fs36 fs16 fs36 midi_set_owner()
fs16
fs36 pard s20 li4636 fi-2520 ri1007 ql tx4636 b0 fs28 fs16
fs28 SUMMARY Acquire ownership of a MIDI device.
fs16
fs28 pard s29 li2116 fi0 ri1007 ql fs16 fs28 SYNOPSIS
pard s5 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b #import <midi/midi_server.h>
fs16
fs28 pard s11 li3124 fi-503 ri1007 ql b0 kern_return_t b midi_set_owner(b0 midi_dev_t i device_porti0 , port_t i owner_porti0 , port_t *i negotiation_portb i0 )
s9 li2116 fi503 fi0 b0 fs16
fs28 ARGUMENTS
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 i device_porti0 : The MIDI device that is to be acquired (retrieved from b netname_look_up()b0 ).
fs16
fs28 i owner_porti0 : The port to register as the owner port.
fs16
fs28 i negotiation_porti0 : 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.
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 DESCRIPTION
pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 The functionb midi_set_owneb0 rb ()b0 establishes ownership of one of the two MIDI devices. The i device_porti0 parameter is obtained by looking up either b midi0b0 or b midi1b0 from the network name server (see the i NeXT Operating System Software i0 manual). The i owner_porti0 parameter is a port to be registered as the owner of this device. When the registered i owner_porti0 is deallocated the device is released. The i negotiation_porti0 parameter is intended to specify a port for negotiating access to the device when it is already busy. However, a negotiation protocol hasn'27t yet been defined, so currently this parameter isn'27t useful.
fs16
fs28 pard s9 li2116 fi0 ri1007 ql fs16
fs28 EXAMPLE
s16 li2620 fi-503 fi0 f2 fs24 port_t device_port, owner_port, negotiation_port;
fi0 kern_return_t error;
fi0
fi0 error = midi_set_owner(device_port, owner_port, &negotiation_port);
fi0 if (error != KERN_SUCCESS) {
fi0 midi_error("midi_set_owner returned value of ", error);
fi0 exit(1);
fi0 }
s9 li2116 fi0 f1 fs28 fs16
fs28 RETURN
pard s17 li3124 fi-503 ri1007 ql tx3124 tx3628 tx4132 KERN_SUCCESS: Ownership has been acquired.
fs16
fs28 MIDI_BAD_PORT: i device_porti0 or i owner_porti0 was invalid.
fs16
fs28 MIDI_PORT_BUSY: The MIDI device is already owned; i negotiation_porti0 contains port to current owner.
fs16
fs28 pard s28 li1108 fi0 ri1007 ql b fs36 fs16
fs36 midi_set_proto() f3 b0 'aef1 b Seeb0 b midi_get_proto()
fs16
fs36 s24 fi-503 fs16
fs36 }These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.