Functions


MIDIDeviceCreate
MIDIDeviceDispose
MIDIDeviceListGetNumberOfDevices
MIDIDeviceListGetDevice
MIDIDeviceListAddDevice
MIDIDeviceListDispose
MIDIEndpointSetRefCons
MIDIEndpointGetRefCons
MIDIGetDriverIORunLoop
MIDIGetDriverDeviceList
MIDIDriverEnableMonitoring

MIDIDeviceCreate


extern OSStatus MIDIDeviceCreate(
    MIDIDriverRef owner, 
    CFStringRef name,
    CFStringRef manufacturer, 
    CFStringRef model,
    MIDIDeviceRef *outDevice) ; 
Parameter Descriptions
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.
function result
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 10.0.

MIDIDeviceDispose


extern OSStatus MIDIDeviceDispose(
    MIDIDeviceRef device); 
Parameter Descriptions
device
The device to be disposed.
function result
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 10.3.

MIDIDeviceListGetNumberOfDevices


extern ItemCount MIDIDeviceListGetNumberOfDevices(
    MIDIDeviceListRef devList) ; 
Parameter Descriptions
devList
The device list.
function result
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 10.0.

MIDIDeviceListGetDevice


extern MIDIDeviceRef MIDIDeviceListGetDevice(
    MIDIDeviceListRef devList,
    ItemCount index0) ; 
Parameter Descriptions
devList
The device list.
deviceIndex0
The index (0...MIDIDeviceListGetNumberOfDevices()-1) of the device to return.
function result
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 10.0.

MIDIDeviceListAddDevice


extern OSStatus MIDIDeviceListAddDevice(
    MIDIDeviceListRef devList,
    MIDIDeviceRef dev) ; 
Parameter Descriptions
devList
The device list.
dev
The device to add to the list.
function result
An OSStatus result code.
Discussion

Add a device to a device list.

Availability
Introduced in Mac OS X 10.0.

MIDIDeviceListDispose


extern OSStatus MIDIDeviceListDispose(
    MIDIDeviceListRef devList) ; 
Parameter Descriptions
devList
The device list to be disposed.
function result
An OSStatus result code.
Discussion

Dispose a device list, but not the contained devices.

Availability
Introduced in Mac OS X 10.1.

MIDIEndpointSetRefCons


extern OSStatus MIDIEndpointSetRefCons(
    MIDIEndpointRef endpt, 
    void *ref1,
    void *ref2); 
Parameter Descriptions
endpt
The endpoint whose refCons are to be set
ref1
The first refCon.
ref2
The second refCon.
function result
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 10.0.

MIDIEndpointGetRefCons


extern OSStatus MIDIEndpointGetRefCons(
    MIDIEndpointRef endpt, 
    void **ref1,
    void **ref2); 
Parameter Descriptions
endpt
The endpoint whose refCons are to be return
ref1
On exit, the first refCon.
ref2
On exit, the second refCon.
function result
An OSStatus result code.
Discussion

Obtain the refCons assigned to the endpoints

Availability
Introduced in Mac OS X 10.0.

MIDIGetDriverIORunLoop


extern CFRunLoopRef MIDIGetDriverIORunLoop(); 
function result
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 10.0.

MIDIGetDriverDeviceList


extern MIDIDeviceListRef MIDIGetDriverDeviceList(
    MIDIDriverRef driver) ; 
Parameter Descriptions
driver
The driver whose devices are to be returned.

function result
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 10.1.

MIDIDriverEnableMonitoring


extern OSStatus MIDIDriverEnableMonitoring(
    MIDIDriverRef driver,
    Boolean enabled) ; 
Parameter Descriptions
driver
The driver whose Monitor function is to be enabled.
enabled
true to enable monitoring, false to disable it.

function result
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 10.1.

(Last Updated February 25, 2005)