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

 


MIDIServices.h

Includes:
<CoreServices/CoreServices.h>
<CoreFoundation/CoreFoundation.h>
<stddef.h>

Overview



This is the header file for Mac OS X's MIDI system services.

API Overview

Drivers own and control Devices, e.g. USB interfaces, PCI cards, etc. A device is defined as a physical object that would be represented by a single icon if there were a graphical view of the studio.

Devices may have multiple logically distinct sub-components, e.g. a MIDI synthesizer and a pair of MIDI ports, both addressable via a USB port. These are called Entities.

Entities have any number of Endpoints, sources and destinations of 16-channel MIDI streams. By grouping a device's endpoints into entities, the system has enough information for an application to make reasonable default assumptions about how to communicate in a bi-directional manner with each entity, as is necessary in MIDI librarian applications.

CoreMIDI attaches a collection of properties to each object it manages. Some properties are dynamic characteristics of a device (e.g. MIDI receive channel and system-exclusive ID's), and some are a matter of user preference (choice of icon, whether the device should appear in lists of possible controllers). Other properties are static and could be looked up in a database, using the device's manufacturer and model names as a key.

Implementation overview

The client API is implemented as the CoreMIDI framework, which uses IPC to communicate with a server process, MIDIServer.

The server process loads, and manages all communication with, MIDI drivers. Most of its implementation is in the CoreMIDIServer framework, which drivers may import in order to access the API.

"Drivers" are not I/O Kit drivers. They are bundles containing CFPlugins.

Many MIDI drivers can simply be user-side I/O Kit clients (probably for serial, USB, Firewire).

PCI card drivers will need their MIDI drivers to communicate with a separate kernel extension.

Note about CoreFoundation data types (CFString, CFData, CFDictionary)

When passing a CF object to a MIDI function, the MIDI function will never consume a reference to the object; the caller always retains a reference which it is responsible for releasing with CFRelease().

When receiving a CF object as a return value from a MIDI function, the caller always receives a new reference to the object, and is responsible for releasing it.



Groups

Endpoints

Group members:

MIDIDestinationCreate
Creates a virtual destination in a client.
MIDIEndpointDispose
Disposes a virtual source or destination your client created.
MIDIEndpointGetEntity
Returns an endpoint's entity.
MIDIGetDestination
Returns one of the destinations in the system.
MIDIGetNumberOfDestinations
Returns the number of destinations in the system.
MIDIGetNumberOfSources
Returns the number of sources in the system.
MIDIGetSource
Returns one of the sources in the system.
MIDISourceCreate
Creates a virtual source in a client.

 

Packet

Lists

Group members:

MIDIPacketListAdd
Adds a MIDI event to a MIDIPacketList.
MIDIPacketListInit
Prepares a MIDIPacketList to be built up dynamically.
MIDIPacketNext
Advances a MIDIPacket pointer to the MIDIPacket which immediately follows it in memory if it is part of a MIDIPacketList.

 

Ports

Group members:

MIDIInputPortCreate
Creates an input port through which the client may receive incoming MIDI messages from any MIDI source.
MIDIOutputPortCreate
Creates an output port through which the client may send outgoing MIDI messages to any MIDI destination.
MIDIPortConnectSource
Establishes a connection from a source to a client's input port.
MIDIPortDisconnectSource
Closes a previously-established source-to-input port connection.
MIDIPortDispose
Disposes a MIDIPort object.

 

Objects

and Properties

Group members:

MIDIObjectFindByUniqueID
Locates a device, external device, entity, or endpoint by its uniqueID.
MIDIObjectGetDataProperty
Gets an object's data-type property.
MIDIObjectGetDictionaryProperty
Gets an object's dictionary-type property.
MIDIObjectGetIntegerProperty
Gets an object's integer-type property.
MIDIObjectGetProperties
Gets all of an object's properties.
MIDIObjectGetStringProperty
Gets an object's string-type property.
MIDIObjectRemoveProperty
Removes an object's property.
MIDIObjectSetDataProperty
Sets an object's data-type property.
MIDIObjectSetDictionaryProperty
Sets an object's dictionary-type property.
MIDIObjectSetIntegerProperty
Sets an object's integer-type property.
MIDIObjectSetStringProperty
Sets an object's string-type property.

 

Entities

Group members:

MIDIEntityGetDestination
Returns one of a given entity's destinations.
MIDIEntityGetDevice
Returns an entity's device.
MIDIEntityGetNumberOfDestinations
Returns the number of destinations in a given entity.
MIDIEntityGetNumberOfSources
Returns the number of sources in a given entity.
MIDIEntityGetSource
Returns one of a given entity's sources.

 

Devices

Group members:

MIDIDeviceGetEntity
Returns one of a given device's entities.
MIDIDeviceGetNumberOfEntities
Returns the number of entities in a given device.
MIDIGetDevice
Returns one of the devices in the system.
MIDIGetNumberOfDevices
Returns the number of devices in the system.

 

I/O

Group members:

MIDIFlushOutput
Unschedules previously-sent packets.
MIDIReceived
Distributes incoming MIDI from a source to the client input ports which are connected to that source.
MIDIRestart
Stops and restarts MIDI I/O.
MIDISend
Sends MIDI to a destination.
MIDISendSysex
Sends a single system-exclusive event, asynchronously.

 

External

Devices

Group members:

MIDIGetExternalDevice
Returns one of the external devices in the system.
MIDIGetNumberOfExternalDevices
Returns the number of external MIDI devices in the system.

 

Clients

Group members:

MIDIClientCreate
Creates a MIDIClient object.
MIDIClientDispose
Disposes a MIDIClient object.

Functions

MIDIClientCreate
Creates a MIDIClient object.
MIDIClientDispose
Disposes a MIDIClient object.
MIDIDestinationCreate
Creates a virtual destination in a client.
MIDIDeviceGetEntity
Returns one of a given device's entities.
MIDIDeviceGetNumberOfEntities
Returns the number of entities in a given device.
MIDIEndpointDispose
Disposes a virtual source or destination your client created.
MIDIEndpointGetEntity
Returns an endpoint's entity.
MIDIEntityGetDestination
Returns one of a given entity's destinations.
MIDIEntityGetDevice
Returns an entity's device.
MIDIEntityGetNumberOfDestinations
Returns the number of destinations in a given entity.
MIDIEntityGetNumberOfSources
Returns the number of sources in a given entity.
MIDIEntityGetSource
Returns one of a given entity's sources.
MIDIFlushOutput
Unschedules previously-sent packets.
MIDIGetDestination
Returns one of the destinations in the system.
MIDIGetDevice
Returns one of the devices in the system.
MIDIGetExternalDevice
Returns one of the external devices in the system.
MIDIGetNumberOfDestinations
Returns the number of destinations in the system.
MIDIGetNumberOfDevices
Returns the number of devices in the system.
MIDIGetNumberOfExternalDevices
Returns the number of external MIDI devices in the system.
MIDIGetNumberOfSources
Returns the number of sources in the system.
MIDIGetSource
Returns one of the sources in the system.
MIDIInputPortCreate
Creates an input port through which the client may receive incoming MIDI messages from any MIDI source.
MIDIObjectFindByUniqueID
Locates a device, external device, entity, or endpoint by its uniqueID.
MIDIObjectGetDataProperty
Gets an object's data-type property.
MIDIObjectGetDictionaryProperty
Gets an object's dictionary-type property.
MIDIObjectGetIntegerProperty
Gets an object's integer-type property.
MIDIObjectGetProperties
Gets all of an object's properties.
MIDIObjectGetStringProperty
Gets an object's string-type property.
MIDIObjectRemoveProperty
Removes an object's property.
MIDIObjectSetDataProperty
Sets an object's data-type property.
MIDIObjectSetDictionaryProperty
Sets an object's dictionary-type property.
MIDIObjectSetIntegerProperty
Sets an object's integer-type property.
MIDIObjectSetStringProperty
Sets an object's string-type property.
MIDIOutputPortCreate
Creates an output port through which the client may send outgoing MIDI messages to any MIDI destination.
MIDIPacketListAdd
Adds a MIDI event to a MIDIPacketList.
MIDIPacketListInit
Prepares a MIDIPacketList to be built up dynamically.
MIDIPacketNext
Advances a MIDIPacket pointer to the MIDIPacket which immediately follows it in memory if it is part of a MIDIPacketList.
MIDIPortConnectSource
Establishes a connection from a source to a client's input port.
MIDIPortDisconnectSource
Closes a previously-established source-to-input port connection.
MIDIPortDispose
Disposes a MIDIPort object.
MIDIReceived
Distributes incoming MIDI from a source to the client input ports which are connected to that source.
MIDIRestart
Stops and restarts MIDI I/O.
MIDISend
Sends MIDI to a destination.
MIDISendSysex
Sends a single system-exclusive event, asynchronously.
MIDISourceCreate
Creates a virtual source in a client.

MIDIClientCreate


Creates a MIDIClient object.

extern OSStatus MIDIClientCreate(
    CFStringRef name, 
    MIDINotifyProc notifyProc, 
    void *notifyRefCon, 
    MIDIClientRef *outClient );  
Parameters
name
The client's name.
notifyProc
An optional (may be NULL) callback function through which the client will receive notifications of changes to the system.
notifyRefCon
A refCon passed back to notifyRefCon
outClient
On successful return, points to the newly-created MIDIClientRef.
Return Value

An OSStatus result code.

Discussion

Note that notifyProc will always be called on the run loop which was current when MIDIClientCreate was first called.

Availability
Introduced in Mac OS X v10.0.

MIDIClientDispose


Disposes a MIDIClient object.

extern OSStatus MIDIClientDispose(
    MIDIClientRef client );  
Parameters
client
The client to dispose.
Return Value

An OSStatus result code.

Discussion

It is not essential to call this function; the CoreMIDI framework will automatically dispose all MIDIClients when an application terminates.

Availability
Introduced in Mac OS X v10.0.

MIDIDestinationCreate


Creates a virtual destination in a client.

extern OSStatus MIDIDestinationCreate(
    MIDIClientRef client, 
    CFStringRef name, 
    MIDIReadProc readProc, 
    void *refCon, 
    MIDIEndpointRef *outDest );  
Parameters
client
The client owning the virtual destination.
name
The name of the virtual destination.
readProc
The MIDIReadProc to be called when a client sends MIDI to the virtual destination.
refCon
The refCon to be passed to the readProc.
outDest
On successful return, a pointer to the newly-created destination.
Return Value

An OSStatus result code.

Discussion

The specified readProc gets called when clients send MIDI to your virtual destination.

Drivers need not call this; when they create devices and entities, sources and destinations are created at that time.

After creating a virtual destination, it's a good idea to assign it the same unique ID it had the last time your application created it. (Although you should be prepared for this to fail in the unlikely event of a collision.) This will permit other clients to retain persistent references to your virtual destination more easily.

See the discussion of kMIDIPropertyAdvanceScheduleTimeMuSec for notes about the relationship between when a sender sends MIDI to the destination and when it is received.

Availability
Introduced in Mac OS X v10.0.

MIDIDeviceGetEntity


Returns one of a given device's entities.

extern MIDIEntityRef MIDIDeviceGetEntity(
    MIDIDeviceRef device, 
    ItemCount entityIndex0 );  
Parameters
device
The device being queried.
entityIndex0
The index (0...MIDIDeviceGetNumberOfEntities(device)-1) of the entity to return

Return Value

A reference to an entity, or NULL if an error occurred.

Availability
Introduced in Mac OS X v10.0.

MIDIDeviceGetNumberOfEntities


Returns the number of entities in a given device.

extern ItemCount MIDIDeviceGetNumberOfEntities(
    MIDIDeviceRef device );  
Parameters
device
The device being queried.

Return Value

The number of entities the device contains, or 0 if an error occurred.

Availability
Introduced in Mac OS X v10.0.

MIDIEndpointDispose


Disposes a virtual source or destination your client created.

extern OSStatus MIDIEndpointDispose(
    MIDIEndpointRef endpt );  
Parameters
endpt
The endpoint to be disposed.

Return Value

An OSStatus result code.

Availability
Introduced in Mac OS X v10.0.

MIDIEndpointGetEntity


Returns an endpoint's entity.

extern OSStatus MIDIEndpointGetEntity(
    MIDIEndpointRef inEndpoint, 
    MIDIEntityRef *outEntity);  
Parameters
inEndpoint
The endpoint being queried.
outEntity
On exit, the endpoint's owning entity, or NULL if none.

Discussion

Virtual sources and destinations don't have entities.

Availability
Introduced in Mac OS X v10.2

MIDIEntityGetDestination


Returns one of a given entity's destinations.

extern MIDIEndpointRef MIDIEntityGetDestination(
    MIDIEntityRef entity, 
    ItemCount destIndex0 );  
Parameters
entity
The entity being queried.
destIndex0
The index (0...MIDIEntityGetNumberOfDestinations(entity) - 1) of the destination to return

Return Value

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

Availability
Introduced in Mac OS X v10.0.

MIDIEntityGetDevice


Returns an entity's device.

extern OSStatus MIDIEntityGetDevice(
    MIDIEntityRef inEntity, 
    MIDIDeviceRef *outDevice);  
Parameters
inEntity
The entity being queried.
outDevice
On successful return, the entity's owning device.

Availability
Introduced in Mac OS X v10.2

MIDIEntityGetNumberOfDestinations


Returns the number of destinations in a given entity.

extern ItemCount MIDIEntityGetNumberOfDestinations(
    MIDIEntityRef entity );  
Parameters
entity
The entity being queried

Return Value

The number of destinations the entity contains, or 0 if an error occurred.

Availability
Introduced in Mac OS X v10.0.

MIDIEntityGetNumberOfSources


Returns the number of sources in a given entity.

extern ItemCount MIDIEntityGetNumberOfSources(
    MIDIEntityRef entity );  
Parameters
entity
The entity being queried

Return Value

The number of sources the entity contains, or 0 if an error occurred.

Availability
Introduced in Mac OS X v10.0.

MIDIEntityGetSource


Returns one of a given entity's sources.

extern MIDIEndpointRef MIDIEntityGetSource(
    MIDIEntityRef entity, 
    ItemCount sourceIndex0 );  
Parameters
entity
The entity being queried.
sourceIndex0
The index (0...MIDIEntityGetNumberOfSources(entity)-1) of the source to return

Return Value

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

Availability
Introduced in Mac OS X v10.0.

MIDIFlushOutput


Unschedules previously-sent packets.

extern OSStatus MIDIFlushOutput(
    MIDIEndpointRef dest );  
Parameters
dest
All pending events scheduled to be sent to this destination are unscheduled. If NULL, the operation applies to all destinations.

Discussion

Clients may use MIDIFlushOutput to cancel the sending of packets that were previously scheduled for future delivery.

Availability
Introduced in Mac OS X v10.1.

MIDIGetDestination


Returns one of the destinations in the system.

extern MIDIEndpointRef MIDIGetDestination(
    ItemCount destIndex0 );  
Parameters
destIndex0
The index (0...MIDIGetNumberOfDestinations()-1) of the destination to return
Return Value

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

Availability
Introduced in Mac OS X v10.0.

MIDIGetDevice


Returns one of the devices in the system.

extern MIDIDeviceRef MIDIGetDevice(
    ItemCount deviceIndex0 );  
Parameters
deviceIndex0
The index (0...MIDIGetNumberOfDevices()-1) of the device to return.
Return Value

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

Discussion

Use this to enumerate the devices in the system.

To enumerate the entities in the system, you can walk through the devices, then walk through the devices' entities.

Note: If a client iterates through the devices and entities in the system, it will not ever visit any virtual sources and destinations created by other clients. Also, a device iteration will return devices which are "offline" (were present in the past but are not currently present), while iterations through the system's sources and destinations will not include the endpoints of offline devices.

Thus clients should usually use MIDIGetNumberOfSources, MIDIGetSource, MIDIGetNumberOfDestinations and MIDIGetDestination, rather iterating through devices and entities to locate endpoints.

Availability
Introduced in Mac OS X v10.0.

MIDIGetExternalDevice


Returns one of the external devices in the system.

extern MIDIDeviceRef MIDIGetExternalDevice(
    ItemCount deviceIndex0 );  
Parameters
deviceIndex0
The index (0...MIDIGetNumberOfDevices()-1) of the device to return.
Return Value

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

Discussion

Use this to enumerate the external devices in the system.

Availability
Introduced in Mac OS X v10.1.

MIDIGetNumberOfDestinations


Returns the number of destinations in the system.

extern ItemCount MIDIGetNumberOfDestinations();  
Return Value

The number of destinations in the system, or 0 if an error occurred.

Availability
Introduced in Mac OS X v10.0.

MIDIGetNumberOfDevices


Returns the number of devices in the system.

extern ItemCount MIDIGetNumberOfDevices();  
Return Value

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

Availability
Introduced in Mac OS X v10.0.

MIDIGetNumberOfExternalDevices


Returns the number of external MIDI devices in the system.

extern ItemCount MIDIGetNumberOfExternalDevices();  
Return Value

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

Discussion

External MIDI devices are MIDI devices connected to driver endpoints via a standard MIDI cable. Their presence is completely optional, only when a UI (such as Audio MIDI Setup) adds them.

Availability
Introduced in Mac OS X v10.1.

MIDIGetNumberOfSources


Returns the number of sources in the system.

extern ItemCount MIDIGetNumberOfSources();  
Return Value

The number of sources in the system, or 0 if an error occurred.

Availability
Introduced in Mac OS X v10.0.

MIDIGetSource


Returns one of the sources in the system.

extern MIDIEndpointRef MIDIGetSource(
    ItemCount sourceIndex0 );  
Parameters
sourceIndex0
The index (0...MIDIGetNumberOfSources()-1) of the source to return
Return Value

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

Availability
Introduced in Mac OS X v10.0.

MIDIInputPortCreate


Creates an input port through which the client may receive incoming MIDI messages from any MIDI source.

extern OSStatus MIDIInputPortCreate(
    MIDIClientRef client, 
    CFStringRef portName, 
    MIDIReadProc readProc, 
    void *refCon, 
    MIDIPortRef *outPort );  
Parameters
client
The client to own the newly-created port.
portName
The name of the port.
readProc
The MIDIReadProc which will be called with incoming MIDI, from sources connected to this port.
refCon
The refCon passed to readHook.
outPort
On successful return, points to the newly-created MIDIPort.
Return Value

An OSStatus result code.

Discussion

After creating a port, use MIDIPortConnectSource to establish an input connection from any number of sources to your port.

readProc will be called on a separate high-priority thread owned by CoreMIDI.

Availability
Introduced in Mac OS X v10.0.

MIDIObjectFindByUniqueID


Locates a device, external device, entity, or endpoint by its uniqueID.

extern OSStatus MIDIObjectFindByUniqueID(
    MIDIUniqueID inUniqueID, 
    MIDIObjectRef *outObject, 
    MIDIObjectType *outObjectType)  ;  
Parameters
inUniqueID
The uniqueID of the object to search for. (This should be the result of an earlier call to MIDIObjectGetIntegerProperty for the property kMIDIPropertyUniqueID).
outObject
The returned object, or NULL if the object was not found or an error occurred. This should be cast to the appropriate type (MIDIDeviceRef, MIDIEntityRef, MIDIEndpointRef), according to *outObjectType.
outObjectType
On exit, the type of object which was found; undefined if none found.
Return Value

An OSStatus error code, including kMIDIObjectNotFound if there is no object with the specified uniqueID.

Availability
Introduced in Mac OS X v10.2

MIDIObjectGetDataProperty


Gets an object's data-type property.

extern OSStatus MIDIObjectGetDataProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID, 
    CFDataRef *outData );  
Parameters
obj
The object whose property is to be returned.
propertyID
Name of the property to return.
outData
On successful return, the value of the property.
Return Value

An OSStatus result code.

Discussion

(See the MIDIObjectRef documentation for information about properties.)

Availability
Introduced in Mac OS X v10.0.

MIDIObjectGetDictionaryProperty


Gets an object's dictionary-type property.

extern OSStatus MIDIObjectGetDictionaryProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID, 
    CFDictionaryRef *outDict ) ;  
Parameters
obj
The object whose property is to be returned.
propertyID
Name of the property to return.
outDict
On successful return, the value of the property.
Return Value

An OSStatus result code.

Discussion

(See the MIDIObjectRef documentation for information about properties.)

Availability
Introduced in Mac OS X v10.2

MIDIObjectGetIntegerProperty


Gets an object's integer-type property.

extern OSStatus MIDIObjectGetIntegerProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID, 
    SInt32 *outValue );  
Parameters
obj
The object whose property is to be returned.
propertyID
Name of the property to return.
outValue
On successful return, the value of the property.
Return Value

An OSStatus result code.

Discussion

(See the MIDIObjectRef documentation for information about properties.)

Availability
Introduced in Mac OS X v10.0.

MIDIObjectGetProperties


Gets all of an object's properties.

extern OSStatus MIDIObjectGetProperties(
    MIDIObjectRef obj, 
    CFPropertyListRef *outProperties, 
    Boolean deep );  
Parameters
obj
The object whose properties are to be returned.
outProperties
On successful return, the object's properties.
deep
true if the object's child objects are to be included (e.g. a device's entities, or an entity's endpoints).
Return Value

An OSStatus result code.

Discussion

Returns a CFPropertyList of all of an object's properties. The property list may be a dictionary or an array. Dictionaries map property names (CFString) to values, which may be CFNumber, CFString, or CFData. Arrays are arrays of such values.

Properties which an object inherits from its owning object (if any) are not included.

Availability
Introduced in Mac OS X v10.1.

MIDIObjectGetStringProperty


Gets an object's string-type property.

extern OSStatus MIDIObjectGetStringProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID, 
    CFStringRef *str );  
Parameters
obj
The object whose property is to be returned.
propertyID
Name of the property to return.
str
On successful return, the value of the property.
Return Value

An OSStatus result code.

Discussion

(See the MIDIObjectRef documentation for information about properties.)

Availability
Introduced in Mac OS X v10.0.

MIDIObjectRemoveProperty


Removes an object's property.

extern OSStatus MIDIObjectRemoveProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID ) ;  
Parameters
obj
The object whose property is to be removed.
propertyID
The property to be removed.
Return Value

An OSStatus result code.

Availability
Introduced in Mac OS X v10.2

MIDIObjectSetDataProperty


Sets an object's data-type property.

extern OSStatus MIDIObjectSetDataProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID, 
    CFDataRef data );  
Parameters
obj
The object whose property is to be altered.
propertyID
Name of the property to set.
data
New value of the property.
Return Value

An OSStatus result code.

Discussion

(See the MIDIObjectRef documentation for information about properties.)

Availability
Introduced in Mac OS X v10.0.

MIDIObjectSetDictionaryProperty


Sets an object's dictionary-type property.

extern OSStatus MIDIObjectSetDictionaryProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID, 
    CFDictionaryRef data );  
Parameters
obj
The object whose property is to be altered.
propertyID
Name of the property to set.
dict
New value of the property.
Return Value

An OSStatus result code.

Discussion

(See the MIDIObjectRef documentation for information about properties.)

Availability
Introduced in Mac OS X v10.2

MIDIObjectSetIntegerProperty


Sets an object's integer-type property.

extern OSStatus MIDIObjectSetIntegerProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID, 
    SInt32 value );  
Parameters
obj
The object whose property is to be altered.
propertyID
Name of the property to set.
value
New value of the property.
Return Value

An OSStatus result code.

Discussion

(See the MIDIObjectRef documentation for information about properties.)

Availability
Introduced in Mac OS X v10.0.

MIDIObjectSetStringProperty


Sets an object's string-type property.

extern OSStatus MIDIObjectSetStringProperty(
    MIDIObjectRef obj, 
    CFStringRef propertyID, 
    CFStringRef str );  
Parameters
obj
The object whose property is to be altered.
propertyID
Name of the property to set.
str
New value of the property.
Return Value

An OSStatus result code.

Discussion

(See the MIDIObjectRef documentation for information about properties.)

Availability
Introduced in Mac OS X v10.0.

MIDIOutputPortCreate


Creates an output port through which the client may send outgoing MIDI messages to any MIDI destination.

extern OSStatus MIDIOutputPortCreate(
    MIDIClientRef client, 
    CFStringRef portName, 
    MIDIPortRef *outPort );  
Parameters
client
The client to own the newly-created port
portName
The name of the port.
outPort
On successful return, points to the newly-created MIDIPort.
Return Value

An OSStatus result code.

Discussion

Output ports provide a mechanism for MIDI merging. CoreMIDI assumes that each output port will be responsible for sending only a single MIDI stream to each destination, although a single port may address all of the destinations in the system.

Multiple output ports are only necessary when an application is capable of directing multiple simultaneous MIDI streams to the same destination.

Availability
Introduced in Mac OS X v10.0.

MIDIPacketListAdd


Adds a MIDI event to a MIDIPacketList.

extern MIDIPacket * MIDIPacketListAdd(
    MIDIPacketList *pktlist, 
    ByteCount listSize, 
    MIDIPacket *curPacket, 
    MIDITimeStamp time, 
    ByteCount nData, 
    const Byte *data);  
Parameters
pktlist
The packet list to which the event is to be added.
listSize
The size, in bytes, of the packet list.
curPacket
A packet pointer returned by a previous call to MIDIPacketListInit or MIDIPacketListAdd for this packet list.
time
The new event's time.
nData
The length of the new event, in bytes.
data
The new event. May be a single MIDI event, or a partial sys-ex event. Running status is not permitted.
Return Value

Returns null if there was not room in the packet for the event; otherwise returns a packet pointer which should be passed as curPacket in a subsequent call to this function.

Discussion

The maximum size of a packet list is 65536 bytes. Large sysex messages must be sent in smaller packet lists.

Availability
Introduced in Mac OS X v10.0.

MIDIPacketListInit


Prepares a MIDIPacketList to be built up dynamically.

extern MIDIPacket * MIDIPacketListInit(
    MIDIPacketList *pktlist );  
Parameters
pktlist
The packet list to be initialized.

Return Value

A pointer to the first MIDIPacket in the packet list.

Availability
Introduced in Mac OS X v10.0.

MIDIPacketNext


Advances a MIDIPacket pointer to the MIDIPacket which immediately follows it in memory if it is part of a MIDIPacketList.

extern MIDIPacket * MIDIPacketNext(
    MIDIPacket *pkt );  
Parameters
pkt
A pointer to a MIDIPacket in a MIDIPacketList.

Return Value

The subsequent packet in the MIDIPacketList.

Discussion

This is implemented as a macro for efficiency and to avoid const problems.


MIDIPortConnectSource


Establishes a connection from a source to a client's input port.

extern OSStatus MIDIPortConnectSource(
    MIDIPortRef port, 
    MIDIEndpointRef source, 
    void *connRefCon );  
Parameters
port
The port to which to create the connection. This port's readProc is called with incoming MIDI from the source.
source
The source from which to create the connection.
connRefCon
This refCon is passed to the MIDIReadProc, as a way to identify the source.
Return Value

An OSStatus result code.

Availability
Introduced in Mac OS X v10.0.

MIDIPortDisconnectSource


Closes a previously-established source-to-input port connection.

extern OSStatus MIDIPortDisconnectSource(
    MIDIPortRef port, 
    MIDIEndpointRef source );  
Parameters
port
The port whose connection is being closed.
source
The source from which to close a connection to the specified port.
Return Value

An OSStatus result code.

Availability
Introduced in Mac OS X v10.0.

MIDIPortDispose


Disposes a MIDIPort object.

extern OSStatus MIDIPortDispose(
    MIDIPortRef port );  
Parameters
port
The port to dispose.
Return Value

An OSStatus result code.

Discussion

It is not usually necessary to call this function; when an application's MIDIClient's are automatically disposed at termination, or explicitly, via MIDIClientDispose, the client's ports are automatically disposed at that time.

Availability
Introduced in Mac OS X v10.0.

MIDIReceived


Distributes incoming MIDI from a source to the client input ports which are connected to that source.

extern OSStatus MIDIReceived(
    MIDIEndpointRef src, 
    const MIDIPacketList *pktlist );  
Parameters
src
The source which is transmitting MIDI.
pktlist
The MIDI events to be transmitted.
Return Value

An OSStatus result code.

Discussion

Drivers should call this function when receiving MIDI from a source.

Clients which have created virtual sources, using MIDISourceCreate, should call this function when the source is generating MIDI.

Unlike MIDISend(), a timestamp of 0 is not equivalent to "now"; the driver or virtual source is responsible for putting proper timestamps in the packets.

Availability
Introduced in Mac OS X v10.0.

MIDIRestart


Stops and restarts MIDI I/O.

extern OSStatus MIDIRestart();  
Return Value

An OSStatus result code.

Discussion

This is useful for forcing CoreMIDI to ask its drivers to rescan for hardware.

Availability
Introduced in Mac OS X v10.1.

MIDISend


Sends MIDI to a destination.

extern OSStatus MIDISend(
    MIDIPortRef port, 
    MIDIEndpointRef dest, 
    const MIDIPacketList *pktlist );  
Parameters
port
The output port through which the MIDI is to be sent.
dest
The destination to receive the events.
pktlist
The MIDI events to be sent.
Return Value

An OSStatus result code.

Discussion

Events with future timestamps are scheduled for future delivery. CoreMIDI performs any needed MIDI merging.

Availability
Introduced in Mac OS X v10.0.

MIDISendSysex


Sends a single system-exclusive event, asynchronously.

extern OSStatus MIDISendSysex(
    MIDISysexSendRequest *request );  
Parameters
request
Contains the destination, and a pointer to the MIDI data to be sent.
Return Value

An OSStatus result code.

Discussion

request->data must point to a single MIDI system-exclusive message, or portion thereof.

Availability
Introduced in Mac OS X v10.0.

MIDISourceCreate


Creates a virtual source in a client.

extern OSStatus MIDISourceCreate(
    MIDIClientRef client, 
    CFStringRef name, 
    MIDIEndpointRef *outSrc );  
Parameters
client
The client owning the virtual source.
name
The name of the virtual source.
outSrc
On successful return, a pointer to the newly-created source.
Return Value

An OSStatus result code.

Discussion

Drivers need not call this; when they create devices and entities, sources and destinations are created at that time.

After creating a virtual source, use MIDIReceived to transmit MIDI messages from your virtual source to any clients connected to the virtual source.

After creating a virtual source, it's a good idea to assign it the same unique ID it had the last time your application created it. (Although you should be prepared for this to fail in the unlikely event of a collision.) This will permit other clients to retain persistent references to your virtual source more easily.

Availability
Introduced in Mac OS X v10.0.

Constants


kMIDIPropertyAdvanceScheduleTimeMuSec


extern const CFStringRef kMIDIPropertyAdvanceScheduleTimeMuSec;  
Discussion

device/entity/endpoint property, integer

Set by the owning driver; should not be touched by other clients. If it is non-zero, then it is a recommendation of how many microseconds in advance clients should schedule output. Clients should treat this value as a minimum. For devices with a non-zero advance schedule time, drivers will receive outgoing messages to the device at the time they are sent by the client, via MIDISend, and the driver is responsible for scheduling events to be played at the right times according to their timestamps.

As of CoreMIDI 1.3, this property may also be set on virtual destinations (but only the creator of the destination should do so). When a client sends to a virtual destination with an advance schedule time of 0, the virtual destination receives its messages at their scheduled delivery time. If a virtual destination has a non-zero advance schedule time, it receives timestamped messages as soon as they are sent, and must do its own internal scheduling of received events.


kMIDIPropertyCanRoute


extern const CFStringRef kMIDIPropertyCanRoute;  // e.g. is patch bay 
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity can route MIDI messages to or from other external MIDI devices (as with MIDI patch bays). This should NOT be set on devices which are controlled by drivers.

New for CoreMIDI 1.3.


kMIDIPropertyConnectionUniqueID


extern const CFStringRef kMIDIPropertyConnectionUniqueID;  
Discussion

device/entity/endpoint property, integer or CFDataRef

UniqueID of an external device/entity/endpoint attached to this one. As of Mac OS X 10.3, Audio MIDI Setup maintains endpoint-to-external endpoint connections (in 10.2, it connected devices to devices). The property is non-existant or 0 if there is no connection.

New for CoreMIDI 1.1 (Mac OS X 10.1)

Beginning with CoreMIDI 1.3, this property may also be a CFDataRef containing an array of big-endian SInt32's, to allow specifying that a driver object connects to multiple external objects (via MIDI thru-ing or splitting).

This property may also exist for external devices/entities/endpoints, in which case it signifies a MIDI Thru connection to another external device/entity/endpoint (again, it is strongly recommended that it be an endpoint).


kMIDIPropertyDeviceID


extern const CFStringRef kMIDIPropertyDeviceID;  
Discussion

device/entity property, integer

The entity's system-exclusive ID, in user-visible form

Drivers may set this property on their devices or entities.

Setup editors may allow the user to set this property on external devices.


kMIDIPropertyDisplayName


extern const CFStringRef kMIDIPropertyDisplayName;  
Discussion

device/entity/endpoint property, string.

Provides the Apple-recommended user-visible name for an endpoint, by combining the device and endpoint names.

For objects other than endpoints, the display name is the same as the name.

New for CoreMIDI 1.5.


kMIDIPropertyDriverDeviceEditorApp


extern const CFStringRef kMIDIPropertyDriverDeviceEditorApp;  
Discussion

device property, string, contains the full path to an application which knows how to configure this driver-owned devices. Drivers may set this property on their owned devices. Applications must not write to it.

New for CoreMIDI 1.4.


kMIDIPropertyDriverOwner


extern const CFStringRef kMIDIPropertyDriverOwner;  
Discussion

device/entity/endpoint property, string

Name of the driver that owns a device. Set by the owning driver, on the device; should not be touched by other clients. Property is inherited from the device by its entities and endpoints.

New for CoreMIDI 1.1 (Mac OS X 10.1)


kMIDIPropertyDriverVersion


extern const CFStringRef kMIDIPropertyDriverVersion;  
Discussion

device/entity/endpoint property, integer, returns the driver version API of the owning driver (only for driver- owned devices). Drivers need not set this property; applications should not write to it.

New for CoreMIDI 1.3.


kMIDIPropertyFactoryPatchNameFile


extern const CFStringRef kMIDIPropertyFactoryPatchNameFile;  
Discussion

device/entity/endpoint property, CFData containing AliasHandle.

An alias to the device's current factory patch name file.

Added in CoreMIDI 1.1 (Mac OS X 10.1). DEPRECATED as of CoreMIDI 1.3. Use kMIDIPropertyNameConfiguration instead.


kMIDIPropertyImage


extern const CFStringRef kMIDIPropertyImage;  
Discussion

device property, CFStringRef which is a full POSIX path to a device or external device's icon, stored in any standard graphic file format such as JPEG, GIF, PNG and TIFF are all acceptable. (See CFURL for functions to convert between POSIX paths and other ways of specifying files.) The image's maximum size should be 128x128.

Drivers should set the icon on the devices they add.

A studio setup editor should allow the user to choose icons for external devices.

New for CoreMIDI 1.3.


kMIDIPropertyIsBroadcast


extern const CFStringRef kMIDIPropertyIsBroadcast;  
Discussion

entity/endpoint property, integer

1 if the endpoint broadcasts messages to all of the other endpoints in the device, 0 if not. Set by the owning driver; should not be touched by other clients. New for CoreMIDI 1.3.


kMIDIPropertyIsDrumMachine


extern const CFStringRef kMIDIPropertyIsDrumMachine;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity's sound presets tend to be collections of non-transposable samples (e.g. drum kits).

New for CoreMIDI 1.3.


kMIDIPropertyIsEffectUnit


extern const CFStringRef kMIDIPropertyIsEffectUnit;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity is primarily a MIDI-controlled audio effect unit (i.e. does not generate sound on its own).

New for CoreMIDI 1.3.


kMIDIPropertyIsEmbeddedEntity


extern const CFStringRef kMIDIPropertyIsEmbeddedEntity;  
Discussion

entity/endpoint property, integer

0 if there are external MIDI connectors, 1 if not. New for CoreMIDI 1.1 (Mac OS X 10.1)


kMIDIPropertyIsMixer


extern const CFStringRef kMIDIPropertyIsMixer;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity mixes external audio signals, controlled by MIDI messages.

New for CoreMIDI 1.3.


kMIDIPropertyIsSampler


extern const CFStringRef kMIDIPropertyIsSampler;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity plays audio samples in response to MIDI note messages.

New for CoreMIDI 1.3.


kMIDIPropertyManufacturer


extern const CFStringRef kMIDIPropertyManufacturer;  
Discussion

device/endpoint property, string

Drivers should set this property on their devices.

Setup editors may allow the user to set this property on external devices.

Creators of virtual endpoints may set this property on their endpoints.


kMIDIPropertyMaxReceiveChannels


extern const CFStringRef kMIDIPropertyMaxReceiveChannels;  
Discussion

device/entity property, integer (0-16). Indicates the maximum number of MIDI channels on which a device may simultaneously receive MIDI Channel Messages. Common values are 0 (devices which only respond to System Messages), 1 (non-multitimbral devices), and 16 (fully multitimbral devices). Other values are possible, for example devices which are multi-timbral but have fewer than 16 "parts".

New for CoreMIDI 1.3.


kMIDIPropertyMaxSysExSpeed


extern const CFStringRef kMIDIPropertyMaxSysExSpeed;  
Discussion

device/entity/endpoint property, integer

Set by the owning driver; should not be touched by other clients. The value is the maximum rate, in bytes/second, at which sysex messages may be sent reliably to this object. (The default value is 3125, as with MIDI 1.0)


kMIDIPropertyMaxTransmitChannels


extern const CFStringRef kMIDIPropertyMaxTransmitChannels;  
Discussion

device/entity property, integer (0/1). Indicates the maximum number of MIDI channels on which a device may simultaneously transmit MIDI Channel Messages. Common values are 0, 1 and 16.

New for CoreMIDI 1.3.


kMIDIPropertyModel


extern const CFStringRef kMIDIPropertyModel;  
Discussion

device/endpoint property, string

Drivers should set this property on their devices.

Setup editors may allow the user to set this property on external devices.

Creators of virtual endpoints may set this property on their endpoints.


kMIDIPropertyName


extern const CFStringRef kMIDIPropertyName;  
Discussion

device/entity/endpoint property, string

Devices, entities, and endpoints may all have names. The recommended way to display an endpoint's name is to ask for the endpoint name, and display only that name if it is unique. If it is non-unique, prepend the device name.

A setup editor may allow the user to set the names of both driver-owned and external devices.


kMIDIPropertyNameConfiguration


extern const CFStringRef kMIDIPropertyNameConfiguration;  
Discussion

device/entity/endpoint property, CFDictionary

This specifies the device's current patch, note and control name values using the MIDINameDocument XML format. This specification requires the use of higher-level, OS-specific constructs outside of the specification, to fully define the current names for a device.

The MIDINameConfiguration property is implementated as a CFDictionary:

key "master" maps to a CFDataRef containing an AliasHandle referring to the device's master name document.

key "banks" maps to a CFDictionaryRef. This dictionary's keys are CFStringRef names of patchBank elements in the master document, and its values are each a CFDictionaryRef: key "file" maps to a CFDataRef containing an AliasHandle to a document containing patches that override those in the master document, and key "patchNameList" maps to a CFStringRef which is the name of the patchNameList element in the overriding document.

key "currentChannelNameSets" maps to a 16-element CFArrayRef, each element of which is a CFStringRef of the name of the current mode for each of the 16 MIDI channels.

key "currentDeviceMode" maps to a CFStringRef containing the name of the device's mode.

Clients setting this property must take particular care to preserve dictionary values other than the ones they are interested in changing, and to properly structure the dictionary.

New for CoreMIDI 1.3.


kMIDIPropertyOffline


extern const CFStringRef kMIDIPropertyOffline;  
Discussion

device/entity/endpoint property, integer

1 = device is offline (is temporarily absent), 0 = present. Set by the owning driver, on the device; should not be touched by other clients. Property is inherited from the device by its entities and endpoints. New for CoreMIDI 1.1 (Mac OS X 10.1)


kMIDIPropertyPanDisruptsStereo


extern const CFStringRef kMIDIPropertyPanDisruptsStereo;  
Discussion

device/entity property, integer (0/1). Indicates whether the MIDI pan messages (control 10), when sent to the device or entity, cause undesirable effects when playing stereo sounds (e.g. converting the signal to mono). New for CoreMIDI 1.3.


kMIDIPropertyPrivate


extern const CFStringRef kMIDIPropertyPrivate;  
Discussion

device/entity/endpoint property, integer

1 = endpoint is private, hidden from other clients. May be set on a device or entity, but they will still appear in the API; only affects whether the owned endpoints are hidden. New for CoreMIDI 1.3.


kMIDIPropertyReceiveChannels


extern const CFStringRef kMIDIPropertyReceiveChannels;  
Discussion

endpoint property, integer

The value is a bitmap of channels on which the object receives: 1=ch 1, 2=ch 2, 4=ch 3 ... 0x8000=ch 16.

Drivers may set this property on their entities or endpoints.

Setup editors may allow the user to set this property on external endpoints.

Virtual destination may set this property on their endpoints.


kMIDIPropertyReceivesBankSelectLSB


extern const CFStringRef kMIDIPropertyReceivesBankSelectLSB;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity responds to MIDI bank select LSB messages (control 32).

New for CoreMIDI 1.3.


kMIDIPropertyReceivesBankSelectMSB


extern const CFStringRef kMIDIPropertyReceivesBankSelectMSB;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity responds to MIDI bank select MSB messages (control 0).

New for CoreMIDI 1.3.


kMIDIPropertyReceivesClock


extern const CFStringRef kMIDIPropertyReceivesClock;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity responds to MIDI beat clock messages.

New for CoreMIDI 1.3.


kMIDIPropertyReceivesMTC


extern const CFStringRef kMIDIPropertyReceivesMTC;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity responds to MIDI Time Code messages.

New for CoreMIDI 1.3.


kMIDIPropertyReceivesNotes


extern const CFStringRef kMIDIPropertyReceivesNotes;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity responds to MIDI Note On messages.

New for CoreMIDI 1.3.


kMIDIPropertyReceivesProgramChanges


extern const CFStringRef kMIDIPropertyReceivesProgramChanges;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity responds to MIDI program change messages.

New for CoreMIDI 1.3.


kMIDIPropertySingleRealtimeEntity


extern const CFStringRef kMIDIPropertySingleRealtimeEntity;  
Discussion

device property, integer

Some MIDI interfaces cannot route MIDI realtime messages to individual outputs; they are broadcast. On such devices the inverse is usually also true -- incoming realtime messages cannot be identified as originating from any particular source.

When this property is set on a driver device, it signifies the 0-based index of the entity on which incoming realtime messages from the device will appear to have originated from.

New for CoreMIDI 1.3.


kMIDIPropertySupportsGeneralMIDI


extern const CFStringRef kMIDIPropertySupportsGeneralMIDI;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity implements the General MIDI specification.

New for CoreMIDI 1.3.


kMIDIPropertySupportsMMC


extern const CFStringRef kMIDIPropertySupportsMMC;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity implements the MIDI Machine Control portion of the MIDI specification.

New for CoreMIDI 1.3.


kMIDIPropertySupportsShowControl


extern const CFStringRef kMIDIPropertySupportsShowControl;  
Discussion

device/entity property, integer (0/1). Indicates whether the device implements the MIDI Show Control specification.

New for CoreMIDI 1.5.


kMIDIPropertyTransmitChannels


extern const CFStringRef kMIDIPropertyTransmitChannels;  
Discussion

endpoint property, integer

The value is a bitmap of channels on which the object transmits: 1=ch 1, 2=ch 2, 4=ch 3 ... 0x8000=ch 16.

New for CoreMIDI 1.3.


kMIDIPropertyTransmitsBankSelectLSB


extern const CFStringRef kMIDIPropertyTransmitsBankSelectLSB;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity transmits MIDI bank select LSB messages (control 32).

New for CoreMIDI 1.3.


kMIDIPropertyTransmitsBankSelectMSB


extern const CFStringRef kMIDIPropertyTransmitsBankSelectMSB;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity transmits MIDI bank select MSB messages (control 0).

New for CoreMIDI 1.3.


kMIDIPropertyTransmitsClock


extern const CFStringRef kMIDIPropertyTransmitsClock;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity transmits MIDI beat clock messages.

New for CoreMIDI 1.3.


kMIDIPropertyTransmitsMTC


extern const CFStringRef kMIDIPropertyTransmitsMTC;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity transmits MIDI Time Code messages.

New for CoreMIDI 1.3.


kMIDIPropertyTransmitsNotes


extern const CFStringRef kMIDIPropertyTransmitsNotes;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity transmits MIDI note messages.

New for CoreMIDI 1.3.


kMIDIPropertyTransmitsProgramChanges


extern const CFStringRef kMIDIPropertyTransmitsProgramChanges;  
Discussion

device/entity property, integer (0/1). Indicates whether the device or entity transmits MIDI program change messages.

New for CoreMIDI 1.3.


kMIDIPropertyUniqueID


extern const CFStringRef kMIDIPropertyUniqueID;  
Discussion

devices, entities, endpoints all have unique ID's, integer

The system assigns unique ID's to all objects. Creators of virtual endpoints may set this property on their endpoints, though doing so may fail if the chosen ID is not unique.


kMIDIPropertyUserPatchNameFile


extern const CFStringRef kMIDIPropertyUserPatchNameFile;  
Discussion

device/entity/endpoint property, CFData containing AliasHandle

An alias to the device's current user patch name file.

Added in CoreMIDI 1.1 (Mac OS X 10.1). DEPRECATED as of CoreMIDI 1.3. Use kMIDIPropertyNameConfiguration instead.

Typedefs


MIDIClientRef


An object maintaining per-client state.

typedef MIDIObjectRef MIDIClientRef;  
Discussion

Derives from MIDIObjectRef, does not have an owner object.

To use CoreMIDI, an application creates a MIDIClientRef, to which it can add MIDIPortRef's, through which it can send and receive MIDI.


MIDICompletionProc


A function called when a system-exclusive event has been completely sent.

typedef void ( *MIDICompletionProc)(
    MIDISysexSendRequest *request);  
Parameters
request
The MIDISysexSendRequest which has completed, or been aborted.
Discussion

Callback function to notify the client of the completion of a call to MIDISendSysex.


MIDIDeviceRef


A MIDI device or external device, containing entities.

typedef MIDIObjectRef MIDIDeviceRef;  
Discussion

Derives from MIDIObjectRef, does not have an owner object.

A MIDI device, which either attaches directly to the computer and is controlled by a MIDI driver, or which is "external," meaning that it is connected to a driver-controlled device via a standard MIDI cable.

A MIDIDeviceRef has properties and contains MIDIEntityRef's.


MIDIEndpointRef


A MIDI source or destination, owned by an entity.

typedef MIDIObjectRef MIDIEndpointRef;  
Discussion

Derives from MIDIObjectRef, owned by a MIDIEntityRef, unless it is a virtual endpoint, in which case there is no owning entity.

Entities have any number of MIDIEndpointRef's, sources and destinations of 16-channel MIDI streams.


MIDIEntityRef


A MIDI entity, owned by a device, containing endpoints.

typedef MIDIObjectRef MIDIEntityRef;  
Discussion

Derives from MIDIObjectRef, owned by a MIDIDeviceRef.

Devices may have multiple logically distinct sub-components, e.g. a MIDI synthesizer and a pair of MIDI ports, both addressable via a USB port.

By grouping a device's endpoints into entities, the system has enough information for an application to make reasonable assumptions about how to communicate in a bi-directional manner with each entity, as is desirable in MIDI librarian applications.

These sub-components are MIDIEntityRef's.


MIDINotifyProc


A callback function for notifying clients of state changes.

typedef void ( *MIDINotifyProc)(
    const MIDINotification *message,
    void *refCon);  
Parameters
message
A structure containing information about what changed.
refCon
The client's refCon passed to MIDIClientCreate.
Discussion

This callback function is called when some aspect of the current MIDI setup changes. It is called on the runloop (thread) on which MIDIClientCreate was first called.


MIDIObjectRef


The base class of many CoreMIDI objects.

typedef UInt32 MIDIObjectRef;  
Discussion

MIDIObject is the base class for many of the objects in CoreMIDI. They have properties, and often an "owner" object, from which they inherit any properties they do not themselves have.

Developers may add their own private properties, whose names must begin with their company's inverted domain name, as in Java package names, but with underscores instead of dots, e.g.: com_apple_APrivateAppleProperty


MIDIPortRef


A MIDI connection port owned by a client.

typedef MIDIObjectRef MIDIPortRef;  
Discussion

Derives from MIDIObjectRef, owned by a MIDIClientRef.

A MIDIPortRef, which may be an input port or output port, is an object through which a client may communicate with any number of MIDI sources or destinations.


MIDIReadProc


A function receiving MIDI input.

typedef void ( *MIDIReadProc)(
    const MIDIPacketList *pktlist,
    void *readProcRefCon,
    void *srcConnRefCon);  
Parameters
pktlist
The incoming MIDI message(s).
readProcRefCon
The refCon you passed to MIDIInputPortCreate or MIDIDestinationCreate
srcConnRefCon
A refCon you passed to MIDIPortConnectSource, which identifies the source of the data.
Discussion

This is a callback function through which a client receives incoming MIDI messages.

A MIDIReadProc function pointer is passed to the MIDIInputPortCreate and MIDIDestinationCreate functions. The CoreMIDI framework will create a high-priority receive thread on your client's behalf, and from that thread, your MIDIReadProc will be called when incoming MIDI messages arrive. Because this function is called from a separate thread, be aware of the synchronization issues when accessing data in this callback.


MIDITimeStamp


A host clock time.

typedef UInt64 MIDITimeStamp;  
Discussion

A host clock time representing the time of an event, as returned by mach_absolute_time() or UpTime().

Since MIDI applications will tend to do a fair amount of math with the times of events, it's more convenient to use a UInt64 than an AbsoluteTime.

See CoreAudio/HostTime.h.


MIDIUniqueID


A unique identifier for a MIDIObjectRef.

typedef SInt32 MIDIUniqueID;  
Discussion

An integer which uniquely identifies a MIDIObjectRef.

Structs and Unions


MIDINotification


A message describing a system state change.

struct MIDINotification { 
    MIDINotificationMessageID messageID; 
    UInt32 messageSize; 
    // additional data may follow, depending on messageID 
};  
Fields
messageID
type of message
messageSize
size of the entire message, including messageID and messageSize
Discussion

A MIDINotification is a structure passed to a MIDINotifyProc, when CoreMIDI wishes to inform a client of a change in the state of the system.


MIDIObjectAddRemoveNotification


A message describing the addition or removal of an object.

struct MIDIObjectAddRemoveNotification { 
    MIDINotificationMessageID messageID; 
    UInt32 messageSize; 
    MIDIObjectRef parent; 
    MIDIObjectType parentType; 
    MIDIObjectRef child; 
    MIDIObjectType childType; 
};  
Fields
messageID
type of message
messageSize
size of the entire message, including messageID and messageSize
parent
the parent of the added or removed object (possibly NULL)
parentType
the type of the parent object (undefined if parent is NULL)
child
the added or removed object
childType
the type of the added or removed object


MIDIObjectPropertyChangeNotification


A message describing the addition or removal of an object.

struct MIDIObjectPropertyChangeNotification { 
    MIDINotificationMessageID messageID; 
    UInt32 messageSize; 
    MIDIObjectRef object; 
    MIDIObjectType objectType; 
    CFStringRef propertyName; 
};  
Fields
messageID
type of message
messageSize
size of the entire message, including messageID and messageSize
object
the object whose property has changed
objectType
the type of the object whose property has changed
propertyName
the name of the changed property


MIDIPacket


A collection of simultaneous MIDI events.

struct MIDIPacket { 
    MIDITimeStamp timeStamp; 
    UInt16 length; 
    Byte data[256]; 
};  
Fields
timeStamp
The time at which the events occurred, if receiving MIDI, or, if sending MIDI, the time at which the events are to be played. Zero means "now." The time stamp applies to the first MIDI byte in the packet.
length
The number of valid MIDI bytes which follow, in data. (It may be larger than 256 bytes if the packet is dynamically allocated.)
data
A variable-length stream of MIDI messages. Running status is not allowed. In the case of system-exclusive messages, a packet may only contain a single message, or portion of one, with no other MIDI events.

The MIDI messages in the packet must always be complete, except for system-exclusive.

(This is declared to be 256 bytes in length so clients don't have to create custom data structures in simple situations.)


MIDIPacketList


A list of MIDI events being received from, or being sent to, one endpoint.

struct MIDIPacketList { 
    UInt32 numPackets; 
    MIDIPacket packet[1]; 
};  
Fields
numPackets
The number of MIDIPackets in the list.
packet
An open-ended array of variable-length MIDIPackets.
Discussion

The timestamps in the packet list must be in ascending order.

Note that the packets in the list, while defined as an array, may not be accessed as an array, since they are variable-length. To iterate through the packets in a packet list, use a loop such as:


MIDIPacket *packet = &packetList->packet[0]; for (int i = 0; i < packetList->numPackets; ++i) { ... packet = MIDIPacketNext(packet); }



MIDISysexSendRequest


A request to transmit a system-exclusive event.

struct MIDISysexSendRequest { 
    MIDIEndpointRef destination; 
    const Byte *data; 
    UInt32 bytesToSend; 
    Boolean complete; 
    Byte reserved[3]; 
    MIDICompletionProc completionProc; 
    void *completionRefCon; 
};  
Fields
destination
The endpoint to which the event is to be sent.
data
Initially, a pointer to the sys-ex event to be sent. MIDISendSysex will advance this pointer as bytes are sent.
bytesToSend
Initially, the number of bytes to be sent. MIDISendSysex will decrement this counter as bytes are sent.
complete
The client may set this to true at any time to abort transmission. The implementation sets this to true when all bytes have been sent.
completionProc
Called when all bytes have been sent, or after the client has set complete to true.
completionRefCon
Passed as a refCon to completionProc.

Discussion

This represents a request to send a single system-exclusive MIDI event to a MIDI destination asynchronously.

Enumerations


Error Constants


The error constants unique to Core MIDI.

enum { 
    kMIDIInvalidClient = -10830, 
    kMIDIInvalidPort = -10831, 
    kMIDIWrongEndpointType = -10832, 
    kMIDINoConnection = -10833, 
    kMIDIUnknownEndpoint = -10834, 
    kMIDIUnknownProperty = -10835, 
    kMIDIWrongPropertyType = -10836, 
    kMIDINoCurrentSetup = -10837, 
    kMIDIMessageSendErr = -10838, 
    kMIDIServerStartErr = -10839, 
    kMIDISetupFormatErr = -10840, 
    kMIDIWrongThread = -10841, 
    kMIDIObjectNotFound = -10842, 
    kMIDIIDNotUnique = -10843 
};  
Constants
kMIDIInvalidClient
An invalid MIDIClientRef was passed.
kMIDIInvalidPort
An invalid MIDIPortRef was passed.
kMIDIWrongEndpointType
A source endpoint was passed to a function expecting a destination, or vice versa.
kMIDINoConnection
Attempt to close a non-existant connection.
kMIDIUnknownEndpoint
An invalid MIDIEndpointRef was passed.
kMIDIUnknownProperty
Attempt to query a property not set on the object.
kMIDIWrongPropertyType
Attempt to set a property with a value not of the correct type.
kMIDINoCurrentSetup
Internal error; there is no current MIDI setup object.
kMIDIMessageSendErr
Communication with MIDIServer failed.
kMIDIServerStartErr
Unable to start MIDIServer.
kMIDISetupFormatErr
Unable to read the saved state.
kMIDIWrongThread
A driver is calling a non-I/O function in the server from a thread other than the server's main thread.
kMIDIObjectNotFound
The requested object does not exist.
kMIDIIDNotUnique
Attempt to set a non-unique kMIDIPropertyUniqueID on an object.
Discussion

These are the error constants that are unique to Core MIDI. Note that Core MIDI functions may return other codes that are not listed here.


MIDINotificationMessageID


Signifies the type of a MIDINotification.

enum { // MIDINotificationMessageID 
    kMIDIMsgSetupChanged = 1, 
    kMIDIMsgObjectAdded = 2, 
    kMIDIMsgObjectRemoved = 3, 
    kMIDIMsgPropertyChanged = 4, 
    kMIDIMsgThruConnectionsChanged = 5, 
    kMIDIMsgSerialPortOwnerChanged = 6, 
    kMIDIMsgIOError = 7 
};  
Constants
kMIDIMsgSetupChanged
Some aspect of the current MIDISetup has changed. No data. Should ignore this message if messages 2-6 are handled.
kMIDIMsgObjectAdded
A device, entity or endpoint was added. Structure is MIDIObjectAddRemoveNotification. New for CoreMIDI 1.3.
kMIDIMsgObjectRemoved
A device, entity or endpoint was removed. Structure is MIDIObjectAddRemoveNotification. New for CoreMIDI 1.3.
kMIDIMsgPropertyChanged
An object's property was changed. Structure is MIDIObjectPropertyChangeNotification. New for CoreMIDI 1.3.
kMIDIMsgThruConnectionsChanged
A persistent MIDI Thru connection was created or destroyed. No data. New for CoreMIDI 1.3.
kMIDIMsgSerialPortOwnerChanged
A persistent MIDI Thru connection was created or destroyed. No data. New for CoreMIDI 1.3.
kMIDIMsgIOError
A driver I/O error occurred.


MIDIObjectType


Signifies the type of a MIDIObject.

enum { // MIDIObjectType 
    kMIDIObjectType_Other = -1, 
    kMIDIObjectType_Device = 0, 
    kMIDIObjectType_Entity = 1, 
    kMIDIObjectType_Source = 2, 
    kMIDIObjectType_Destination = 3,  
    kMIDIObjectType_ExternalMask = 0x10, 
    kMIDIObjectType_ExternalDevice = kMIDIObjectType_ExternalMask | kMIDIObjectType_Device, 
    kMIDIObjectType_ExternalEntity = kMIDIObjectType_ExternalMask | kMIDIObjectType_Entity, 
    kMIDIObjectType_ExternalSource = kMIDIObjectType_ExternalMask | kMIDIObjectType_Source, 
    kMIDIObjectType_ExternalDestination = kMIDIObjectType_ExternalMask | kMIDIObjectType_Destination 
};  
Discussion

Signifies the real type of a MIDIObjectRef instance.


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