MIDIClientCreate |
Creates a MIDIClient object.
extern OSStatus MIDIClientCreate( CFStringRef name, MIDINotifyProc notifyProc, void *notifyRefCon, MIDIClientRef *outClient );
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.
Note that notifyProc will always be called on the run loop which was current when
MIDIClientCreate was first called.
MIDIClientDispose |
Disposes a MIDIClient object.
extern OSStatus MIDIClientDispose( MIDIClientRef client );
client
- The client to dispose.
It is not essential to call this function; the CoreMIDI framework will automatically dispose all MIDIClients when an application terminates.
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 );
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.
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.
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 );
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.
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.
MIDIPortDispose |
Disposes a MIDIPort object.
extern OSStatus MIDIPortDispose( MIDIPortRef port );
port
- The port to dispose.
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.
MIDIPortConnectSource |
Establishes a connection from a source to a client's input port.
extern OSStatus MIDIPortConnectSource( MIDIPortRef port, MIDIEndpointRef source, void *connRefCon );
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.
MIDIPortDisconnectSource |
Closes a previously-established source-to-input port connection.
extern OSStatus MIDIPortDisconnectSource( MIDIPortRef port, MIDIEndpointRef source );
port
- The port whose connection is being closed.
source
- The source from which to close a connection to the specified port.
MIDIGetNumberOfDevices |
Returns the number of devices in the system.
extern ItemCount MIDIGetNumberOfDevices();
MIDIGetDevice |
Returns one of the devices in the system.
extern MIDIDeviceRef MIDIGetDevice( ItemCount deviceIndex0 );
deviceIndex0
- The index (0...MIDIGetNumberOfDevices()-1) of the device to return.
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.
MIDIDeviceGetNumberOfEntities |
Returns the number of entities in a given device.
extern ItemCount MIDIDeviceGetNumberOfEntities( MIDIDeviceRef device );
device
- The device being queried.
MIDIDeviceGetEntity |
Returns one of a given device's entities.
extern MIDIEntityRef MIDIDeviceGetEntity( MIDIDeviceRef device, ItemCount entityIndex0 );
device
- The device being queried.
entityIndex0
- The index (0...MIDIDeviceGetNumberOfEntities(device)-1) of the entity to return
MIDIEntityGetNumberOfSources |
Returns the number of sources in a given entity.
extern ItemCount MIDIEntityGetNumberOfSources( MIDIEntityRef entity );
entity
- The entity being queried
MIDIEntityGetSource |
Returns one of a given entity's sources.
extern MIDIEndpointRef MIDIEntityGetSource( MIDIEntityRef entity, ItemCount sourceIndex0 );
entity
- The entity being queried.
sourceIndex0
- The index (0...MIDIEntityGetNumberOfSources(entity)-1) of the source to return
MIDIEntityGetNumberOfDestinations |
Returns the number of destinations in a given entity.
extern ItemCount MIDIEntityGetNumberOfDestinations( MIDIEntityRef entity );
entity
- The entity being queried
MIDIEntityGetDestination |
Returns one of a given entity's destinations.
extern MIDIEndpointRef MIDIEntityGetDestination( MIDIEntityRef entity, ItemCount destIndex0 );
entity
- The entity being queried.
destIndex0
- The index (0...MIDIEntityGetNumberOfDestinations(entity) - 1) of the destination to return
MIDIEntityGetDevice |
Returns an entity's device.
extern OSStatus MIDIEntityGetDevice( MIDIEntityRef inEntity, MIDIDeviceRef *outDevice);
inEntity
- The entity being queried.
outDevice
- On successful return, the entity's owning device.
MIDIGetNumberOfSources |
Returns the number of sources in the system.
extern ItemCount MIDIGetNumberOfSources();
MIDIGetSource |
Returns one of the sources in the system.
extern MIDIEndpointRef MIDIGetSource( ItemCount sourceIndex0 );
sourceIndex0
- The index (0...MIDIGetNumberOfSources()-1) of the source to return
MIDIGetNumberOfDestinations |
Returns the number of destinations in the system.
extern ItemCount MIDIGetNumberOfDestinations();
MIDIGetDestination |
Returns one of the destinations in the system.
extern MIDIEndpointRef MIDIGetDestination( ItemCount destIndex0 );
destIndex0
- The index (0...MIDIGetNumberOfDestinations()-1) of the destination to return
MIDIEndpointGetEntity |
Returns an endpoint's entity.
extern OSStatus MIDIEndpointGetEntity( MIDIEndpointRef inEndpoint, MIDIEntityRef *outEntity);
inEndpoint
- The endpoint being queried.
outEntity
- On exit, the endpoint's owning entity, or NULL if none.
Virtual sources and destinations don't have entities.
MIDIDestinationCreate |
Creates a virtual destination in a client.
extern OSStatus MIDIDestinationCreate( MIDIClientRef client, CFStringRef name, MIDIReadProc readProc, void *refCon, MIDIEndpointRef *outDest );
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.
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.
MIDISourceCreate |
Creates a virtual source in a client.
extern OSStatus MIDISourceCreate( MIDIClientRef client, CFStringRef name, MIDIEndpointRef *outSrc );
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.
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.
MIDIEndpointDispose |
Disposes a virtual source or destination your client created.
extern OSStatus MIDIEndpointDispose( MIDIEndpointRef endpt );
endpt
- The endpoint to be disposed.
MIDIGetNumberOfExternalDevices |
Returns the number of external MIDI devices in the system.
extern ItemCount MIDIGetNumberOfExternalDevices();
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.
MIDIGetExternalDevice |
Returns one of the external devices in the system.
extern MIDIDeviceRef MIDIGetExternalDevice( ItemCount deviceIndex0 );
deviceIndex0
- The index (0...MIDIGetNumberOfDevices()-1) of the device to return.
Use this to enumerate the external devices in the system.
MIDIObjectGetIntegerProperty |
Gets an object's integer-type property.
extern OSStatus MIDIObjectGetIntegerProperty( MIDIObjectRef obj, CFStringRef propertyID, SInt32 *outValue );
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.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectSetIntegerProperty |
Sets an object's integer-type property.
extern OSStatus MIDIObjectSetIntegerProperty( MIDIObjectRef obj, CFStringRef propertyID, SInt32 value );
obj
- The object whose property is to be altered.
propertyID
- Name of the property to set.
value
- New value of the property.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectGetStringProperty |
Gets an object's string-type property.
extern OSStatus MIDIObjectGetStringProperty( MIDIObjectRef obj, CFStringRef propertyID, CFStringRef *str );
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.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectSetStringProperty |
Sets an object's string-type property.
extern OSStatus MIDIObjectSetStringProperty( MIDIObjectRef obj, CFStringRef propertyID, CFStringRef str );
obj
- The object whose property is to be altered.
propertyID
- Name of the property to set.
str
- New value of the property.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectGetDataProperty |
Gets an object's data-type property.
extern OSStatus MIDIObjectGetDataProperty( MIDIObjectRef obj, CFStringRef propertyID, CFDataRef *outData );
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.
(See the MIDIObjectRef documentation for information
about properties.)
MIDIObjectSetDataProperty |
Sets an object's data-type property.
extern OSStatus MIDIObjectSetDataProperty( MIDIObjectRef obj, CFStringRef propertyID, CFDataRef data );
obj
- The object whose property is to be altered.
propertyID
- Name of the property to set.
data
- New value of the property.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectGetDictionaryProperty |
Gets an object's dictionary-type property.
extern OSStatus MIDIObjectGetDictionaryProperty( MIDIObjectRef obj, CFStringRef propertyID, CFDictionaryRef *outDict ) ;
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.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectSetDictionaryProperty |
Sets an object's dictionary-type property.
extern OSStatus MIDIObjectSetDictionaryProperty( MIDIObjectRef obj, CFStringRef propertyID, CFDictionaryRef data );
obj
- The object whose property is to be altered.
propertyID
- Name of the property to set.
dict
- New value of the property.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectGetProperties |
Gets all of an object's properties.
extern OSStatus MIDIObjectGetProperties( MIDIObjectRef obj, CFPropertyListRef *outProperties, Boolean deep );
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).
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.
MIDIObjectRemoveProperty |
Removes an object's property.
extern OSStatus MIDIObjectRemoveProperty( MIDIObjectRef obj, CFStringRef propertyID ) ;
obj
- The object whose property is to be removed.
propertyID
- The property to be removed.
MIDIObjectFindByUniqueID |
Locates a device, external device, entity, or endpoint by its uniqueID.
extern OSStatus MIDIObjectFindByUniqueID( MIDIUniqueID inUniqueID, MIDIObjectRef *outObject, MIDIObjectType *outObjectType) ;
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.
MIDISend |
Sends MIDI to a destination.
extern OSStatus MIDISend( MIDIPortRef port, MIDIEndpointRef dest, const MIDIPacketList *pktlist );
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.
Events with future timestamps are scheduled for future delivery. CoreMIDI performs any needed MIDI merging.
MIDISendSysex |
Sends a single system-exclusive event, asynchronously.
extern OSStatus MIDISendSysex( MIDISysexSendRequest *request );
request
- Contains the destination, and a pointer to the MIDI data to be sent.
request->data must point to a single MIDI system-exclusive message, or portion thereof.
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 );
src
- The source which is transmitting MIDI.
pktlist
- The MIDI events to be transmitted.
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.
MIDIFlushOutput |
Unschedules previously-sent packets.
extern OSStatus MIDIFlushOutput( MIDIEndpointRef dest );
dest
- All pending events scheduled to be sent to this destination are unscheduled. If NULL, the operation applies to all destinations.
Clients may use MIDIFlushOutput to cancel the sending of packets that were previously scheduled for future delivery.
MIDIRestart |
Stops and restarts MIDI I/O.
extern OSStatus MIDIRestart();
This is useful for forcing CoreMIDI to ask its drivers to rescan for hardware.
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 );
pkt
- A pointer to a MIDIPacket in a MIDIPacketList.
This is implemented as a macro for efficiency and to avoid const problems.
MIDIPacketListInit |
Prepares a MIDIPacketList to be built up dynamically.
extern MIDIPacket * MIDIPacketListInit( MIDIPacketList *pktlist );
pktlist
- The packet list to be initialized.
MIDIPacketListAdd |
Adds a MIDI event to a MIDIPacketList.
extern MIDIPacket * MIDIPacketListAdd( MIDIPacketList *pktlist, ByteCount listSize, MIDIPacket *curPacket, MIDITimeStamp time, ByteCount nData, const Byte *data);
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.
The maximum size of a packet list is 65536 bytes. Large sysex messages must be sent in smaller packet lists.
(Last Updated February 25, 2005)