ADC Home > Reference Library > Reference > Audio > Core Audio > Core MIDI Server Framework Reference

MIDIDriver.h

Includes:

Overview

This is the header file for Mac OS X's MIDI driver interface.

About MIDI drivers

MIDI drivers are CFPlugIns, installed into the following places:

    /System/Library/Extensions      -- not recommended for non-Apple drivers, but
                                    necessary for compatibility with CoreMIDI 1.0
    
    /Library/Audio/MIDI Drivers     -- starting with CoreMIDI 1.1
    
    ~/Library/Audio/MIDI Drivers    -- starting with CoreMIDI 1.1

Refer to the CFPlugIn documentation for more information about plug-ins.

Driver bundle/plug-in properties

A driver's bundle settings should include settings resembling the following:

    Bundle settings:
        CFBundleIdentifier              String          com.mycompany.midi.driver.mydevice
            (note that this will be the driver's persistent ID in MIDISetup's)
        CFPlugInDynamicRegistration     String          NO
        CFPlugInFactories               Dictionary      1 key/value pair
            [your new factory UUID]     String          [your factory function name]
        CFPlugInTypes                   Dictionary      1 key/value pair
            ECDE9574-0FE4-11D4-BB1A-0050E4CEA526        Array       1 object
                (this is kMIDIDriverTypeID)
                0                       String          [your new factory UUID]
    Build settings:
        WRAPPER_EXTENSION               plugin

Driver access to the CoreMIDI API

Drivers have access to most of the CoreMIDI API. They should link with CoreMIDIServer.framework, not CoreMIDI.framework.

Unlike applications, drivers communicate with the server directly, not through Mach messaging. This necessitates some limitations on the contexts from which a driver may call the server.

The MIDI I/O functions MIDISend and MIDIReceived may be called from any thread.

All other CoreMIDI functions must only be called from the server's main thread, which is the thread on which the driver is created and from which all calls to the driver other than Send() are made.

COM Interfaces

MIDIDriverInterface: The COM-style interface to a MIDI driver.

Functions

MIDIDeviceCreate
MIDIDeviceDispose
MIDIDeviceListAddDevice
MIDIDeviceListDispose
MIDIDeviceListGetDevice
MIDIDeviceListGetNumberOfDevices
MIDIDriverEnableMonitoring
MIDIEndpointGetRefCons
MIDIEndpointSetRefCons
MIDIGetDriverDeviceList
MIDIGetDriverIORunLoop

MIDIDeviceCreate

extern OSStatus MIDIDeviceCreate(
    MIDIDriverRef owner, 
    CFStringRef name,
    CFStringRef manufacturer, 
    CFStringRef model,
    MIDIDeviceRef *outDevice) ;

Parameters

owner: The driver creating the device. NULL if a non-driver.
name: The name of the new device.
manufacturer: The name of the device's manufacturer.
model: The device's model name.
outDevice: On successful return, points to the newly-created device.

Return Value

An OSStatus result code.

Discussion

Drivers call this function to create new MIDIDevice objects corresponding to the hardware that is present.

Non-drivers may call this function as of CoreMIDI 1.1, to create external devices.

Availability: Introduced in Mac OS X v10.0.

MIDIDeviceDispose

extern OSStatus MIDIDeviceDispose(
    MIDIDeviceRef device);

Parameters

device: The device to be disposed.

Return Value

An OSStatus result code.

Discussion

Drivers may call this function to dispose MIDIDevice objects which have not yet been added to the system via MIDISetupAddDevice. Once a device has been added to the system with MIDISetupAddDevice, the driver must not use this call to destroy it; it must use MIDISetupRemoveDevice to do so.

Non-drivers do not have access to this function; they must call MIDISetupAddDevice and MIDISetupRemoveDevice.

Availability: Introduced in Mac OS X v10.3.

MIDIDeviceListAddDevice

extern OSStatus MIDIDeviceListAddDevice(
    MIDIDeviceListRef devList,
    MIDIDeviceRef dev) ;

Parameters

devList: The device list.
dev: The device to add to the list.

Return Value

An OSStatus result code.

Discussion

Add a device to a device list.

Availability: Introduced in Mac OS X v10.0.

MIDIDeviceListDispose

extern OSStatus MIDIDeviceListDispose(
    MIDIDeviceListRef devList) ;

Parameters

devList: The device list to be disposed.

Return Value

An OSStatus result code.

Discussion

Dispose a device list, but not the contained devices.

Availability: Introduced in Mac OS X v10.1.

MIDIDeviceListGetDevice

extern MIDIDeviceRef MIDIDeviceListGetDevice(
    MIDIDeviceListRef devList,
    ItemCount index0) ;

Parameters

devList: The device list.
deviceIndex0: The index (0...MIDIDeviceListGetNumberOfDevices()-1) of the device to return.

Return Value

A reference to a device, or NULL if an error occurred.

Discussion

Return one of the devices in a device list.

Availability: Introduced in Mac OS X v10.0.

MIDIDeviceListGetNumberOfDevices

extern ItemCount MIDIDeviceListGetNumberOfDevices(
    MIDIDeviceListRef devList) ;

Parameters

devList: The device list.

Return Value

The number of devices in the list, or 0 if an error occurred.

Discussion

Returns the number of devices in a device list.

Availability: Introduced in Mac OS X v10.0.

MIDIDriverEnableMonitoring

extern OSStatus MIDIDriverEnableMonitoring(
    MIDIDriverRef driver,
    Boolean enabled) ;

Parameters

driver: The driver whose Monitor function is to be enabled.
enabled: true to enable monitoring, false to disable it.

Return Value

An OSStatus result code.

Discussion

A driver may make this call to have MIDIServer pass it every outgoing MIDI packet, to all destinations in the system (not just those controlled by itself).

Availability: Introduced in Mac OS X v10.1.

MIDIEndpointGetRefCons

extern OSStatus MIDIEndpointGetRefCons(
    MIDIEndpointRef endpt, 
    void **ref1,
    void **ref2);

Parameters

endpt: The endpoint whose refCons are to be return
ref1: On exit, the first refCon.
ref2: On exit, the second refCon.

Return Value

An OSStatus result code.

Discussion

Obtain the refCons assigned to the endpoints

Availability: Introduced in Mac OS X v10.0.

MIDIEndpointSetRefCons

extern OSStatus MIDIEndpointSetRefCons(
    MIDIEndpointRef endpt, 
    void *ref1,
    void *ref2);

Parameters

endpt: The endpoint whose refCons are to be set
ref1: The first refCon.
ref2: The second refCon.

Return Value

An OSStatus result code.

Discussion

Drivers need an efficient way to translate from a MIDIEndpoint (source or destination) to their own internal data structures corresponding to that endpoint. This function provides a way for the driver to assign its own refCons to endpoints.

These refCons are passed back to the driver in its Send() and Flush() methods.

RefCons are not persistent (i.e. they are not saved as part of a MIDISetup). They need to be re-initialized in each call to Start().

A typical use is to use one refCon to refer to a device, and a second to refer to a port on the device.

Availability: Introduced in Mac OS X v10.0.

MIDIGetDriverDeviceList

extern MIDIDeviceListRef MIDIGetDriverDeviceList(
    MIDIDriverRef driver) ;

Parameters

driver: The driver whose devices are to be returned.

Return Value

The requested device list.

Discussion

Returns the list of devices which are in the current MIDISetup and which were created/owned by the specified driver.

The returned device list should be disposed (using MIDIDeviceListDispose) by the caller.

Availability: Introduced in Mac OS X v10.1.

MIDIGetDriverIORunLoop

extern CFRunLoopRef MIDIGetDriverIORunLoop();

Return Value

The CFRunLoopRef of the server's driver I/O thread.

Discussion

Drivers typically need to receive asynchronous I/O completion callbacks on a high-priority thread. To save drivers from the trouble of creating their own threads for this purpose, and to make efficient use of system resources, the MIDIServer provides a thread which drivers may use.

Drivers should do as little work as possible in this thread; typically, just dequeueing and encoding output packets, and decoding input packets into MIDIPacketLists to be passed to MIDIReceived.

This is a realtime-priority thread and shouldn't be used for anything other than I/O. For lower-priority tasks, drivers can use the runloop which was current when they were constructed.

Availability: Introduced in Mac OS X v10.0.

Constants

kMIDIDriverPropertyUsesSerial

extern const CFStringRef kMIDIDriverPropertyUsesSerial;

Discussion

This constant, "MIDIDriverUsesSerial", when defined to "YES" in a driver's bundle, tells MIDIServer that the driver uses serial ports and is eligible to have serial ports assigned to it.

When a serial driver's Start() method is called, it should use MIDIGetSerialPortOwner to discover which serial ports it has been assigned to use, and only use those ports.

New for CoreMIDI 1.1.

Typedefs

MIDIDeviceListRef

typedef MIDIObjectRef MIDIDeviceListRef;

Discussion

A MIDIDeviceListRef is a list of MIDIDeviceRef's. The devices are not owned by the list (i.e., disposing the list does not dispose the devices it references).

MIDIDriverRef

typedef MIDIDriverInterface ** MIDIDriverRef;

Discussion

Points to a pointer to a MIDIDriverInterface, a CFPlugIn structure (defined in MIDIDriver.h) containing function pointers for the driver's methods. Only the MIDIServer may call a driver's methods.

#defines

kMIDIDriverInterface2ID

The UUID for version 2 of the MIDI driver interface.

#define kMIDIDriverInterface2ID \ 
    CFUUIDGetConstantUUIDWithBytes(NULL, 0x43, 0xC9, 0x8C, 0x3C, 0x30, 0x6C, 0x11, 0xD5, 0xAF, 0x73, 0x00, 0x30, 0x65, 0xA8, 0x30, 0x1E)

Discussion

See the description of the MIDIDriverInterface structure for information about different versions of the MIDI driver interface.

The version 2 driver interface is available beginning with CoreMIDI 1.1.

kMIDIDriverInterfaceID

The UUID for version 1 of the MIDI driver interface.

#define kMIDIDriverInterfaceID \ 
    CFUUIDGetConstantUUIDWithBytes(NULL, 0x49, 0xDF, 0xCA, 0x9E, 0x0F, 0xE5, 0x11, 0xD4, 0x95, 0x0D, 0x00, 0x50, 0xE4, 0xCE, 0xA5, 0x26)

Discussion

See the description of the MIDIDriverInterface structure for information about different versions of the MIDI driver interface.

kMIDIDriverTypeID

The UUID for MIDI driver plugins.

#define kMIDIDriverTypeID \ 
    CFUUIDGetConstantUUIDWithBytes(NULL, 0xEC, 0xDE, 0x95, 0x74, 0x0F, 0xE4, 0x11, 0xD4, 0xBB, 0x1A, 0x00, 0x50, 0xE4, 0xCE, 0xA5, 0x26)

Discussion

kMIDIDriverTypeID should be entered into your driver's bundle settings as follows:

CFPlugInTypes                   Dictionary      1 key/value pair
	ECDE9574-0FE4-11D4-BB1A-0050E4CEA526        Array       1 object
		(this is kMIDIDriverTypeID)
		0                       String          [your new factory UUID]

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