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

Handling Replies

midi_reply_handler()

SUMMARY	Dispatch messages sent asynchronously from the MIDI driver.

SYNOPSIS
#import <midi/midi_reply_handler.h>

kern_return_t midi_reply_handler(msg_header_t *msg, midi_reply_t *midi_reply)

ARGUMENTS
msg:  Pointer to message received from MIDI driver.

midi_reply:  Pointer to the dispatch structure (see description).

DESCRIPTION
The function midi_reply_handler() parses certain messages sent asynchronously by the driver, and then calls the appropriate one of several application-implemented functions.

Specifically, midi_get_data() and midi_output_queue_notify() cause the driver to send messages asynchronously to the reply port specified in those calls.  (The maximum size of these messages is MIDI_REPLY_INMSG_SIZE.)  The application should retrieve each of these messages by calling msg_receive() (see the NeXT Operating System Software manual).  It should then examine the msg_local_port field of the message structure to verify that it's the same port as the reply port.  If so, it should pass a pointer to the received message as the first argument (msg) to midi_reply_handler().

The second argument, midi_reply, is a pointer to a structure of the following type:

typedef struct midi_reply {
    kern_return_t (*ret_raw_data)(
        void           *arg,
        midi_raw_t      midi_raw_data,
        u_int           midi_raw_dataCnt);
    kern_return_t (*ret_cooked_data)(
        void           *arg,
        midi_cooked_t   midi_cooked_data,
        u_int           midi_cooked_dataCnt);
    kern_return_t (*ret_packed_data)(
        void           *arg,
        u_int           quanta,
        midi_packed_t   midi_packed_data,
        u_int           midi_packed_dataCnt);
    kern_return_t (*queue_notify)(
        void           *arg,
        u_int           queue_size);
    void *arg;            // argument to pass to function
    int   timeout;        // timeout for RPC return msg_send
} midi_reply_t;

This structure describes how the received message is to be dispatched.  The first four fields of the structure are pointers to application-supplied functions.  If the received message contains incoming MIDI data (resulting from an invocation of midi_get_data()), midi_reply_handler() calls the appropriate one of the first three functions, depending on whether the data is raw, cooked, or packed.  Similarly, if the received message is a notification of available space in the output queue (resulting from an invocation of midi_output_queue_notify()), midi_reply_handler() calls the fourth function.

Each application-supplied function is passed the void * arg element from the structure as its first parameter.  If no function is specified (that is, the value of the appropriate structure member is zero), the received message is discarded.

For example code, see /NextDeveloper/Examples/MidiDriver.

RETURN
KERN_SUCCESS:  Message dispatched.

midi_timer_reply_handler()

SUMMARY	Dispatch messages sent asynchronously from the timer.

SYNOPSIS
#import <midi/midi_timer_reply_handler.h>

kern_return_t midi_timer_reply_handler(msg_header_t *msg, midi_timer_reply_t *midi_timer_reply)

ARGUMENTS
msg:  Pointer to message received from timer.

midi_timer_reply:  Pointer to the dispatch structure (see description).

DESCRIPTION
The function midi_timer_reply_handler() parses messages sent asynchronously by the timer, and then calls an appropriate application-implemented function.

Specifically, timer_timeval_req() and timer_quanta_req() cause the timer to send messages asynchronously to the timer reply port specified in those calls.  (The maximum size of such a message is MIDI_TIMER_REPLY_INMSG_SIZE.)  The application should retrieve each of these messages by calling msg_receive() (see the NeXT Operating System Software manual).  It should then examine the msg_local_port field of the message structure to verify that it's the same port as the timer reply port.  (This port should be different from the reply port used by midi_get_data() and midi_output_queue_notify().  Messages on that reply port should instead be handled by midi_reply_handler().)  If the local port is the timer reply port, the application should pass a pointer to the received message as the first argument (msg) to midi_timer_reply_handler().

The second argument, midi_timer_reply, is a pointer to a structure of the following type:

typedef struct midi_timer_reply {
    kern_return_t (*timer_event)(
        void               *arg,
        timeval_t           timeval,
        u_int               quanta,
        u_int               usec_per_quantum,
        u_int               real_usec_per_quantum,
        boolean_t           timer_expired,
        boolean_t           timer_stopped,
        boolean_t           timer_forward);
    void *arg;                  // argument to pass to function
    int   timeout;              // timeout for RPC return msg_send
} midi_timer_reply_t;

This structure describes how the received message is to be dispatched.  The first field of the structure is a pointer to an application-supplied function that midi_timer_reply_handler() will call.  This application-supplied function is passed the void * arg element from the structure as its first parameter.  If no function is specified (that is, the value of the first structure member is zero), the received message is discarded.

The application-supplied function is passed timeval and quanta parameters that indicate the time that the event occurred.  The usec_per_quantum parameter specifies the number of microseconds per quantum.  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.

For example code, see /NextDeveloper/Examples/MidiDriver.

RETURN
KERN_SUCCESS:  Message dispatched.