NAME

timer_timeval_req, timer_quanta_req, timer_set, timer_set_quantum, timer_stop, timer_start, timer_direction, midi_timer_reply_handler, midi_timer_error, midi_timer_error_string − MIDI timer interface

SYNOPSIS

#include <midi/midi_timer.h>
#include <midi/midi_timer_reply_handler.h>
#include <midi/midi_timer_error.h>
 kern_return_t timer_timeval_req (
port_ttimer_port,
port_treply_port,
timeval_ttimeval,
boolean_trelative_time)
 kern_return_t timer_quanta_req (
port_ttimer_port,
port_treply_port,
intquanta,
boolean_trelative_time)
 kern_return_t timer_set (
port_ttimer_port,
port_t control_port,
timeval_ttimeval)
 kern_return_t timer_set_quantum (
port_ttimer_port,
port_tcontrol_port,
u_intusec_per_quantum)
 kern_return_t timer_stop (
port_ttimer_port,
port_tcontrol_port)
 kern_return_t timer_start (
port_ttimer_port,
port_tcontrol_port)
 kern_return_t timer_direction (
port_ttimer_port,
port_tcontrol_port,
boolean_tforward)
 kern_return_t midi_timer_reply_handler (
msg_header_t ∗msg,
midi_timer_reply_t ∗midi_timer_reply)
 void midi_timer_error(const char ∗s, kern_return_t r)
 const char ∗midi_timer_error_string(kern_return_t r)

DESCRIPTION

The MIDI device driver implements a timer service, primarily for use in timestamping MIDI events.  The timer allows users to query the time and ask for events relative to the timer’s time−base.  With the timer control port (the registered MIDI owner port, in this case) the timer can be started and stopped.  Its direction can be changed, and the value of the timer’s time−base can be modified.  In turn, the timer will notify active users (those with pending timer events) when anything changes in the timer.  (See The NeXT System Reference Manual for more details on MIDI timer implementation). 

Timer_timeval_req requests that the timer issue an event when the requested time has arrived.  The timer_port parameter is the port representing the timer service.  This can be obtained from the MIDI driver (see midi(4)).  The timeval parameter specifies the time of the requested notification in seconds and microseconds (as implemented by the timer service).  The relative_time parameter, if true, indicates that the time stored in timeval should be treated as being relative to the current timer service time.  Otherwise, the event will be delivered using timeval 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 either of the following conditions arises:

1) The timer expires. 

2) The timer changes from running to being stopped. 

3) The timer starts running again. 

4) The timer changes direction (was counting upwards, now counting downwards, or was counting downwards, now counting upwards). 

5) 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.

Timer_quanta_req behaves the same as timer_timeval_req with the exception the the requested time is represented as quanta rather than the seconds and microseconds contained in a timeval structure. 

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.  Any active requests will be sent timer events indicating that the time has changed. 

Timer_set_quantum specifies the number of microseconds per quantum that is to be used by this timer.  Access to the timer control_port is required for this operation. 

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. 

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. 

Timer_direction causes the timer to start running in the specified direction.  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. 

Certain calls on the timer 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_timer_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_timer_reply_t structure (see <midi/midi_timer_reply_handler.h>).  The maximum size message that the timer may send asynchronously is MIDI_TIMER_REPLY_INMSG_SIZE.  The structure referenced by midi_timer_reply contains pointers to (user supplied) routine that will be called when the corresponding message is received.  It also contains a void ∗ argument that is passed as the first parameter to the user−supplied routine.  If no routine is specified (value of the structure member is zero) the message is thrown away.  The routine that the user must implement follows:

 kern_return_t (∗timer_event)(
void ∗arg,
timeval_ttimeval,
u_intquanta,
u_intusec_per_quantum,
u_intreal_usec_per_quantum,
boolean_ttimer_expired,
boolean_ttimer_stopped,
boolean_ttimer_forward);
 

The timeval and quanta parameters indicate the time that the event occured.  The usec_per_quantum parameter specifies the number of microseconds per quanta.  The real_usec_per_quantum parameter specifies the number of microseconds per quantum with respect to the system clock, rather than the timer’s notion of seconds and microseconds.  The timer_expired parameter, if set, indicates that the event that was requested has expired.  No further events will occur on this port.  If not set, it indicates that some other aspect of the timer has changed.  The timer_stopped parameter indicates whether the timer is started or stopped.  The timer_forward parameter indicates the direction in which the timer is changing, either forwards or backwards. 

Midi_timer_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_timer_error_string returns the error string associated with the specified error as would be used by midi_timer_error. 

ERRORS

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

TIMER_BAD_PARM
A parameter passed to this routine was invalid.

TIMER_BAD_CNTRL
The control_port passed is not the registered control_port.

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

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

NOTES

For this release, the timer may only run in the forward direction. 

SEE ALSO

kern_loader(8), midi(4). 

NeXT, Inc.  —  25 June 1989