ADC Home > Reference Library > Reference > Audio > Core Audio > Core MIDI Framework Reference
|
MIDIServices.h |
Includes: | <CoreServices/CoreServices.h> <CoreFoundation/CoreFoundation.h> <stddef.h> |
This is the header file for Mac OS X's MIDI system services.
- 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.
Lists
- 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.
- 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.
and Properties
- 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.
- 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.
- 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.
- 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.
Devices
- MIDIGetExternalDevice
- Returns one of the external devices in the system.
- MIDIGetNumberOfExternalDevices
- Returns the number of external MIDI devices in the system.
- MIDIClientCreate
- Creates a MIDIClient object.
- MIDIClientDispose
- Disposes a MIDIClient object.
MIDIClientCreate |
Creates a MIDIClient object.
extern OSStatus MIDIClientCreate( CFStringRef name, MIDINotifyProc notifyProc, void *notifyRefCon, MIDIClientRef *outClient );
name
notifyProc
notifyRefCon
outClient
An OSStatus result code.
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
An OSStatus result code.
It is not essential to call this function; the CoreMIDI framework will automatically dispose all MIDIClients when an application terminates.
MIDIDestinationCreate |
Creates a virtual destination in a client.
extern OSStatus MIDIDestinationCreate( MIDIClientRef client, CFStringRef name, MIDIReadProc readProc, void *refCon, MIDIEndpointRef *outDest );
client
name
readProc
refCon
outDest
An OSStatus result code.
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.
MIDIDeviceGetEntity |
Returns one of a given device's entities.
extern MIDIEntityRef MIDIDeviceGetEntity( MIDIDeviceRef device, ItemCount entityIndex0 );
device
entityIndex0
A reference to an entity, or NULL if an error occurred.
MIDIDeviceGetNumberOfEntities |
Returns the number of entities in a given device.
extern ItemCount MIDIDeviceGetNumberOfEntities( MIDIDeviceRef device );
device
The number of entities the device contains, or 0 if an error occurred.
MIDIEndpointDispose |
Disposes a virtual source or destination your client created.
extern OSStatus MIDIEndpointDispose( MIDIEndpointRef endpt );
endpt
An OSStatus result code.
MIDIEndpointGetEntity |
Returns an endpoint's entity.
extern OSStatus MIDIEndpointGetEntity( MIDIEndpointRef inEndpoint, MIDIEntityRef *outEntity);
inEndpoint
outEntity
Virtual sources and destinations don't have entities.
MIDIEntityGetDestination |
Returns one of a given entity's destinations.
extern MIDIEndpointRef MIDIEntityGetDestination( MIDIEntityRef entity, ItemCount destIndex0 );
entity
destIndex0
A reference to a destination, or NULL if an error occurred.
MIDIEntityGetDevice |
Returns an entity's device.
extern OSStatus MIDIEntityGetDevice( MIDIEntityRef inEntity, MIDIDeviceRef *outDevice);
inEntity
outDevice
MIDIEntityGetNumberOfDestinations |
Returns the number of destinations in a given entity.
extern ItemCount MIDIEntityGetNumberOfDestinations( MIDIEntityRef entity );
entity
The number of destinations the entity contains, or 0 if an error occurred.
MIDIEntityGetNumberOfSources |
Returns the number of sources in a given entity.
extern ItemCount MIDIEntityGetNumberOfSources( MIDIEntityRef entity );
entity
The number of sources the entity contains, or 0 if an error occurred.
MIDIEntityGetSource |
Returns one of a given entity's sources.
extern MIDIEndpointRef MIDIEntityGetSource( MIDIEntityRef entity, ItemCount sourceIndex0 );
entity
sourceIndex0
A reference to a source, or NULL if an error occurred.
MIDIFlushOutput |
Unschedules previously-sent packets.
extern OSStatus MIDIFlushOutput( MIDIEndpointRef dest );
dest
Clients may use MIDIFlushOutput to cancel the sending of packets that were previously scheduled for future delivery.
MIDIGetDestination |
Returns one of the destinations in the system.
extern MIDIEndpointRef MIDIGetDestination( ItemCount destIndex0 );
destIndex0
A reference to a destination, or NULL if an error occurred.
MIDIGetDevice |
Returns one of the devices in the system.
extern MIDIDeviceRef MIDIGetDevice( ItemCount deviceIndex0 );
deviceIndex0
A reference to a device, or NULL if an error occurred.
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.
MIDIGetExternalDevice |
Returns one of the external devices in the system.
extern MIDIDeviceRef MIDIGetExternalDevice( ItemCount deviceIndex0 );
deviceIndex0
A reference to a device, or NULL if an error occurred.
Use this to enumerate the external devices in the system.
MIDIGetNumberOfDestinations |
Returns the number of destinations in the system.
extern ItemCount MIDIGetNumberOfDestinations();
The number of destinations in the system, or 0 if an error occurred.
MIDIGetNumberOfDevices |
Returns the number of devices in the system.
extern ItemCount MIDIGetNumberOfDevices();
The number of devices in the system, or 0 if an error occurred.
MIDIGetNumberOfExternalDevices |
Returns the number of external MIDI devices in the system.
extern ItemCount MIDIGetNumberOfExternalDevices();
The number of external devices in the system, or 0 if an error
occurred.
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.
MIDIGetNumberOfSources |
Returns the number of sources in the system.
extern ItemCount MIDIGetNumberOfSources();
The number of sources in the system, or 0 if an error occurred.
MIDIGetSource |
Returns one of the sources in the system.
extern MIDIEndpointRef MIDIGetSource( ItemCount sourceIndex0 );
sourceIndex0
A reference to a source, or NULL if an error occurred.
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
portName
readProc
refCon
outPort
An OSStatus result code.
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.
MIDIObjectFindByUniqueID |
Locates a device, external device, entity, or endpoint by its uniqueID.
extern OSStatus MIDIObjectFindByUniqueID( MIDIUniqueID inUniqueID, MIDIObjectRef *outObject, MIDIObjectType *outObjectType) ;
inUniqueID
outObject
outObjectType
An OSStatus error code, including kMIDIObjectNotFound if there
is no object with the specified uniqueID.
MIDIObjectGetDataProperty |
Gets an object's data-type property.
extern OSStatus MIDIObjectGetDataProperty( MIDIObjectRef obj, CFStringRef propertyID, CFDataRef *outData );
obj
propertyID
outData
An OSStatus result code.
(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
propertyID
outDict
An OSStatus result code.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectGetIntegerProperty |
Gets an object's integer-type property.
extern OSStatus MIDIObjectGetIntegerProperty( MIDIObjectRef obj, CFStringRef propertyID, SInt32 *outValue );
obj
propertyID
outValue
An OSStatus result code.
(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
outProperties
deep
An OSStatus result code.
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.
MIDIObjectGetStringProperty |
Gets an object's string-type property.
extern OSStatus MIDIObjectGetStringProperty( MIDIObjectRef obj, CFStringRef propertyID, CFStringRef *str );
obj
propertyID
str
An OSStatus result code.
(See the MIDIObjectRef documentation for information about properties.)
MIDIObjectRemoveProperty |
Removes an object's property.
extern OSStatus MIDIObjectRemoveProperty( MIDIObjectRef obj, CFStringRef propertyID ) ;
obj
propertyID
An OSStatus result code.
MIDIObjectSetDataProperty |
Sets an object's data-type property.
extern OSStatus MIDIObjectSetDataProperty( MIDIObjectRef obj, CFStringRef propertyID, CFDataRef data );
obj
propertyID
data
An OSStatus result code.
(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
propertyID
dict
An OSStatus result code.
(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
propertyID
value
An OSStatus result code.
(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
propertyID
str
An OSStatus result code.
(See the MIDIObjectRef documentation for information about properties.)
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
portName
outPort
An OSStatus result code.
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.
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
listSize
curPacket
time
nData
data
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.
The maximum size of a packet list is 65536 bytes. Large sysex messages must be sent in smaller packet lists.
MIDIPacketListInit |
Prepares a MIDIPacketList to be built up dynamically.
extern MIDIPacket * MIDIPacketListInit( MIDIPacketList *pktlist );
pktlist
A pointer to the first MIDIPacket in the packet list.
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
The subsequent packet in the MIDIPacketList.
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 );
port
source
connRefCon
An OSStatus result code.
MIDIPortDisconnectSource |
Closes a previously-established source-to-input port connection.
extern OSStatus MIDIPortDisconnectSource( MIDIPortRef port, MIDIEndpointRef source );
port
source
An OSStatus result code.
MIDIPortDispose |
Disposes a MIDIPort object.
extern OSStatus MIDIPortDispose( MIDIPortRef port );
port
An OSStatus result code.
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.
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
pktlist
An OSStatus result code.
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.
MIDIRestart |
Stops and restarts MIDI I/O.
extern OSStatus MIDIRestart();
An OSStatus result code.
This is useful for forcing CoreMIDI to ask its drivers to rescan for hardware.
MIDISend |
Sends MIDI to a destination.
extern OSStatus MIDISend( MIDIPortRef port, MIDIEndpointRef dest, const MIDIPacketList *pktlist );
port
dest
pktlist
An OSStatus result code.
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
An OSStatus result code.
request->data must point to a single MIDI system-exclusive message, or portion thereof.
MIDISourceCreate |
Creates a virtual source in a client.
extern OSStatus MIDISourceCreate( MIDIClientRef client, CFStringRef name, MIDIEndpointRef *outSrc );
client
name
outSrc
An OSStatus result code.
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.
kMIDIPropertyAdvanceScheduleTimeMuSec |
extern const CFStringRef kMIDIPropertyAdvanceScheduleTimeMuSec;
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
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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.
MIDIClientRef |
An object maintaining per-client state.
typedef MIDIObjectRef MIDIClientRef;
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);
request
- The MIDISysexSendRequest which has completed, or been aborted.
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;
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;
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;
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);
message
- A structure containing information about what changed.
refCon
- The client's refCon passed to MIDIClientCreate.
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;
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;
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);
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.
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;
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;
An integer which uniquely identifies a MIDIObjectRef.
MIDINotification |
A message describing a system state change.
struct MIDINotification { MIDINotificationMessageID messageID; UInt32 messageSize; // additional data may follow, depending on messageID };
messageID
- type of message
messageSize
- size of the entire message, including messageID and messageSize
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; };
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; };
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]; };
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]; };
numPackets
- The number of MIDIPackets in the list.
packet
- An open-ended array of variable-length MIDIPackets.
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; };
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.
This represents a request to send a single system-exclusive MIDI event to a MIDI destination asynchronously.
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 };
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.
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 };
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 };
Signifies the real type of a MIDIObjectRef instance.
|