Contact ADC

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

MIDIServices.h

Includes:

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)