This is the header file for Mac OS X's MIDI driver interface.
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.
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
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.
MIDIDeviceCreate |
extern OSStatus MIDIDeviceCreate( MIDIDriverRef owner, CFStringRef name, CFStringRef manufacturer, CFStringRef model, MIDIDeviceRef *outDevice) ;
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.
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.
MIDIDeviceDispose |
extern OSStatus MIDIDeviceDispose( MIDIDeviceRef device);
device
- The device to be disposed.
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.
MIDIDeviceListGetNumberOfDevices |
extern ItemCount MIDIDeviceListGetNumberOfDevices( MIDIDeviceListRef devList) ;
devList
- The device list.
Returns the number of devices in a device list.
MIDIDeviceListGetDevice |
extern MIDIDeviceRef MIDIDeviceListGetDevice( MIDIDeviceListRef devList, ItemCount index0) ;
devList
- The device list.
deviceIndex0
- The index (0...MIDIDeviceListGetNumberOfDevices()-1) of the device to return.
Return one of the devices in a device list.
MIDIDeviceListAddDevice |
extern OSStatus MIDIDeviceListAddDevice( MIDIDeviceListRef devList, MIDIDeviceRef dev) ;
devList
- The device list.
dev
- The device to add to the list.
Add a device to a device list.
MIDIDeviceListDispose |
extern OSStatus MIDIDeviceListDispose( MIDIDeviceListRef devList) ;
devList
- The device list to be disposed.
Dispose a device list, but not the contained devices.
MIDIEndpointSetRefCons |
extern OSStatus MIDIEndpointSetRefCons( MIDIEndpointRef endpt, void *ref1, void *ref2);
endpt
- The endpoint whose refCons are to be set
ref1
- The first refCon.
ref2
- The second refCon.
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.
MIDIEndpointGetRefCons |
extern OSStatus MIDIEndpointGetRefCons( MIDIEndpointRef endpt, void **ref1, void **ref2);
endpt
- The endpoint whose refCons are to be return
ref1
- On exit, the first refCon.
ref2
- On exit, the second refCon.
Obtain the refCons assigned to the endpoints
MIDIGetDriverIORunLoop |
extern CFRunLoopRef MIDIGetDriverIORunLoop();
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.
MIDIGetDriverDeviceList |
extern MIDIDeviceListRef MIDIGetDriverDeviceList( MIDIDriverRef driver) ;
driver
- The driver whose devices are to be returned.
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.
MIDIDriverEnableMonitoring |
extern OSStatus MIDIDriverEnableMonitoring( MIDIDriverRef driver, Boolean enabled) ;
driver
- The driver whose Monitor function is to be enabled.
enabled
- true to enable monitoring, false to disable it.
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).
kMIDIDriverPropertyUsesSerial |
extern const CFStringRef kMIDIDriverPropertyUsesSerial;
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.
MIDIDriverRef |
typedef MIDIDriverInterface ** MIDIDriverRef;
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.
MIDIDeviceListRef |
typedef struct OpaqueMIDIDeviceList* MIDIDeviceListRef;
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).
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)
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)
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)
See the description of the MIDIDriverInterface structure for information about different versions of the MIDI driver interface.
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)
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.
(Last Updated February 25, 2005)