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

Timer Operations

midi_get_in_timer_port()

SUMMARY	Get the timer service used by this MIDI device for input.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_get_in_timer_port(midi_rx_t rx_port, port_t *timer_port)

ARGUMENTS
rx_port:  MIDI receive or transmit port.

timer_port:  Pointer to the timer port to use.

DESCRIPTION
The function midi_get_in_timer_port() returns a pointer to the port representing the timer that's being used by the MIDI receive or transmit port (specified by rx_port).  Currently, this must be the default timer implemented by the driver, which is also returned by midi_get_out_timer_port().

RETURN
KERN_SUCCESS:  Timer port was returned.

MIDI_BAD_PORT:  Rx _port is invalid.

midi_get_out_timer_port()

SUMMARY	Get the timer service implemented by this MIDI device.

SYNOPSIS
#import <midi/midi_server.h>

kern_return_t midi_get_out_timer_port(midi_dev_t device_port, port_t *timer_port)

ARGUMENTS
device_port:  The MIDI device port.

timer_port:  Pointer to the timer port implemented by this MIDI device.

DESCRIPTION
The function midi_get_out_timer_port() returns a pointer to the timer port implemented by this MIDI device.  The ownership port isn't required to obtain this port as it can't be used to control MIDI itself.  It may be useful for other processes, which can synchronize themselves to MIDI input or output by using the same clock that's used by the device itself.

RETURN
KERN_SUCCESS:  Timer port was returned.

MIDI_NO_OWNER:  MIDI device does not have an owner.

timer_direction()

SUMMARY	Cause the timer to start incrementing in the specified direction.

SYNOPSIS
#import <midi/midi_timer.h>

kern_return_t timer_direction(port_t timer_port, port_t control_port, boolean_t forward)

ARGUMENTS
timer_port:  The timer port to use (obtainable by midi_get_out_timer_port()).

control_port:  Port controlling this timer.

forward:  Whether to run timer forwards instead of backwards.

DESCRIPTION
The function timer_direction() causes the timer to start running in the direction specified by forward.  Access to the timer control_port is required for this operation.  Any active requests will be sent timer events indicating that the time has changed.

RETURN
KERN_SUCCESS:  Timer direction set.

TIMER_BAD_CNTRL:  control_port is invalid.

TIMER_UNSUP:  Operation is not supported.

timer_quanta_req(), timer_timeval_req()

SUMMARY	Request a timer event at some time in the future.

SYNOPSIS
#import <midi/midi_timer.h>

kern_return_t timer_quanta_req(port_t timer_port, port_t reply_port, int quanta, boolean_t relative_time)
kern_return_t timer_timeval_req(port_t timer_port, port_t reply_port, timeval_t timeval, boolean_t relative_time)

ARGUMENTS
timer_port:  The timer port to use.

reply_port:  Where to send timer events.

timeval:  Time of requested event, in seconds and microseconds.

quanta:  Time of requested event, specified in quanta.

relative_time:  Whether the time in timeval (or in quanta) is specified relative to the current time, instead of as an absolute time.

DESCRIPTION
The functions timer_timeval_req() and timer_quanta_req() request that the timer issue an event when the requested time has arrived.  The two functions behave the same, except that timer_timeval_req() represents the requested time as a timeval structure (consisting of seconds and microseconds), whereas timer_quanta_req() represents time in arbitrary units called quanta.  (See timer_set_quantum().)

The timer_port parameter is the port representing the timer service.  This port should be obtained from the MIDI driver with midi_get_out_timer_port().  The timeval or quanta parameter specifies the time of the requested notification (as implemented by the timer service).  The relative_time parameter, if true, indicates that the current timer service time should be used as an offset to add to the requested time (stored in timeval or quanta).  Otherwise, the event will be delivered using the requested time as an absolute time.  The reply_port parameter specifies the port to which the timer event is to be delivered.  An event is delivered when any of the following conditions arises:

·	The timer expires.

·	The timer changes from running to stopped.

·	The timer starts running again.

·	The timer changes direction (it was counting upwards but now is counting downwards, or vice versa).

·	The value of the timer changes.

Once the timer expires, the event is cleared and no further messages will be delivered on the registered reply_port.  Each reply_port can have only a single event scheduled.  Scheduling another event causes the existing event to be cleared.  Multiple events can be received by using distinct reply_ports.

	Warning:	The MIDI driver doesn't sort messages by time.  Thus, if the second of two calls to timer_timeval_req() or timer_quanta_req() requests an event whose time is earlier than that requested by the first call, the driver won't issue the second event until after the time requested by the first call.

RETURN
KERN_SUCCESS:  Timer event now pending.

timer_set()

SUMMARY	Set the value of the timer.

SYNOPSIS
#import <midi/midi_timer.h>

kern_return_t timer_set(port_t timer_port, port_t control_port, timeval_t timeval)

ARGUMENTS
timer_port:  The timer port to use (obtainable by midi_get_out_timer_port).

control_port:  Port controlling this timer.

timeval:  Time to set timer to.

DESCRIPTION
The function timer_set() sets the time of the timer service to the time specified in the timeval parameter.  Access to the timer control_port is required for this operation (for the MIDI driver's timer, the control port is the device's owner port).  Any active requests will be sent timer events indicating that the time has changed.

RETURN
KERN_SUCCESS:  Timer value changed.

TIMER_BAD_CNTRL:  control_port is invalid

timer_set_quantum()

SUMMARY	Set the number of microseconds per timer quantum.

SYNOPSIS
#import <midi/midi_timer.h>

kern_return_t timer_set_quantum(port_t timer_port, port_t control_port, u_int quantum)

ARGUMENTS
timer_port:  The timer port to use (obtainable by midi_get_out_timer_port).

control_port:  Port controlling this timer.

quantum:  Specified number of microseconds per quantum.

DESCRIPTION
The function timer_set_quantum() specifies the number of microseconds per quantum that is to be used by this timer.  The default value of a quantum is 1000 microseconds.  Access to the timer control_port is required for this operation.

RETURN
KERN_SUCCESS:  Timer quantum set.

TIMER_BAD_CNTRL:  control_port is invalid.

timer_start()

SUMMARY	Start the timer running.

SYNOPSIS
#import <midi/midi_timer.h>

kern_return_t timer_start(port_t timer_port, port_t control_port)

ARGUMENTS
timer_port:  The timer port to use (obtainable by midi_get_out_timer_port).

control_port:  Port controlling this timer.

DESCRIPTION
The function timer_start() causes the timer to resume execution.  Access to the timer control_port is required for this operation.  Any active requests will be sent timer events indicating that the time has changed.

RETURN
KERN_SUCCESS:  Timer started.

TIMER_BAD_CNTRL:  control_port is invalid.

timer_stop()

SUMMARY	Stop the timer from incrementing.

SYNOPSIS
#import <midi/midi_timer.h>

kern_return_t timer_stop(port_t timer_port, port_t control_port)

ARGUMENTS
timer_port:  The timer port to use (obtainable by midi_get_out_timer_port).

control_port:  Port controlling this timer.

DESCRIPTION
The function timer_stop() causes the timer to stop updating.  Access to the timer control_port is required for this operation.  Any active requests will be sent timer events indicating that the time has changed.

RETURN
KERN_SUCCESS:  Timer stopped.

TIMER_BAD_CNTRL:  control_port is invalid.

timer_timeval_req ® See timer_quanta_req