MIDIDriverInterface

Overview

The COM-style interface to a MIDI driver.

Discussion

This is the function table interface to a MIDI driver. Both version 1 and 2 drivers use this same table of function pointers (except as noted).

Drivers which support both the version 1 and version 2 interfaces can tell which version of the server is running by checking to see whether kMIDIDriverInterface2ID or kMIDIDriverInterfaceID is passed to the factory function. If the version 1 interface is requested, the driver should behave as if it is a version 1 driver.

Functions

Configure

EnableSource

FindDevices

Flush

Monitor

Send

Start

Stop

OSStatus ( *Configure)(
    MIDIDriverRef self,
    MIDIDeviceRef device);  

Discussion

not currently used

OSStatus ( *EnableSource)(
    MIDIDriverRef self,
    MIDIEndpointRef src,
    Boolean enabled);  

Discussion

A client has opened or closed a connection, and now the server is telling the driver that input from a particular source either does or does not have any listeners in the system. The driver may use this information to decide whether to pass messages from the source to the server, and it may even be able to tell the source hardware not to generate incoming MIDI I/O for that source.

OSStatus ( *FindDevices)(
    MIDIDriverRef self,
    MIDIDeviceListRef devList);  

Discussion

This is only called for version 1 drivers. The server is requesting that the driver detect the devices which are present. For each device present, the driver should create a MIDIDeviceRef with entities, using MIDIDeviceCreate and MIDIDeviceAddEntity, and add the device to the supplied MIDIDeviceListRef, using MIDIDeviceListAddDevice.

The driver should not retain any references to the created devices and entities.

OSStatus ( *Flush)(
    MIDIDriverRef self,
    MIDIEndpointRef dest,
    void *destRefCon1,
    void *destRefCon2);  

Discussion

Only for version 2 drivers (new for CoreMIDI 1.1).

Drivers which support schedule-ahead, when receiving this message, should unschedule all pending output to the specified destination. If the destination is null, the driver should unschedule all pending output to all destinations.

OSStatus ( *Monitor)(
    MIDIDriverRef self,
    MIDIEndpointRef dest,
    const MIDIPacketList *pktlist);  

Discussion

Only for version 2 drivers (new for CoreMIDI 1.1).

Some specialized drivers (e.g. a MIDI monitor display) may wish to intercept and look at all outgoing MIDI messages. After a driver calls MIDIDriverEnableMonitoring(true) on itself, this function is called with the outgoing MIDI packets for all destinations in the system. The Monitor function cannot rely on the MIDI events arriving in order, due to MIDIServer's schedule-ahead facilities.

OSStatus ( *Send)(
    MIDIDriverRef self,
    const MIDIPacketList *pktlist,
    void *destRefCon1,
    void *destRefCon2);  

Discussion

Send a MIDIPacketList to the destination endpoint whose refCons are being passed as arguments.

OSStatus ( *Start)(
    MIDIDriverRef self,
    MIDIDeviceListRef devList);  

Discussion

The server is telling the driver to begin MIDI I/O.

The provided device list contains the devices which were previously located by FindDevices (in the case of a version 1 driver), or the devices which are owned by this driver and are currently in the current MIDISetup (for version 2 drivers).

The provided devices may or may not still be present. A version 1 driver should attempt to use as many of the devices as are actually present.

A version 2 driver may make calls such as MIDISetupAddDevice, MIDIDeviceAddEntity, MIDIDeviceRemoveEntity to dynamically modify the system's current state. For devices in the provided device list which are not present, the driver should set their kMIDIPropertyOffline property to 1. A version 2 driver may also set up notifications when the IORegistry changes, to detect connection and disconnection of devices it wishes to control. At these times also, the driver may change the devices' kMIDIPropertyOffline, and dynamically modify the system's current state to reflect the devices which are present. When passing a CFRunLoopRef to IOKit for notification purposes, the driver must use the server's main runloop, which is obtained with CFRunLoopGetCurrent().

The driver will probably want to iterate through the destination endpoints and assign their driver refCons, so as to identify multiple destinations when Send() is called.

The provided device list remains owned by the system and can be assumed to contain only devices owned by this driver. The driver may retain references to the devices in this list and any it creates while running.

OSStatus ( *Stop)(
    MIDIDriverRef self);  

Discussion

The server is telling the driver to terminate MIDI I/O. All I/O operations that were begun in Start, or as a result of a subsequent IOKit notification, should be terminated.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11