This header defines functions that manipulate and customize the global state of the MIDI system. These functions are generally only needed by applications which wish to allow the user some flexibility in how the MIDI system's state is presented, and by MIDI drivers, which may dynamically modify the system state as hardware is connected and disconnected.
MIDISetupCreate |
Interrogates drivers, to discover what hardware is present.
As of CoreMIDI 1.1, it is usually not necessary to call
this function, as CoreMIDI manages a single persistent
MIDISetup itself.
extern OSStatus MIDISetupCreate( MIDISetupRef *outSetup );
outSetup
- On successful return, points to a newly-created MIDISetup object. The caller is responsible for disposing it, or transferring ownership of the object back to the system, with MIDISetupInstall.
MIDISetupDispose |
Dispose a MIDISetup object.
As of CoreMIDI 1.1, it is usually not necessary to call
this function, as CoreMIDI manages a single persistent
MIDISetup itself.
extern OSStatus MIDISetupDispose( MIDISetupRef setup );
setup
- The MIDISetup to be disposed.
MIDISetupInstall |
Install a MIDISetup as the system's current state.
A client can create a MIDISetup object using
MIDISetupCreate, or MIDISetupFromData. This function will
install this state as the current state of the system,
possibly changing the devices visible to clients.
As of CoreMIDI 1.1, it is usually not necessary to call
this function, as CoreMIDI manages a single persistent
MIDISetup itself.
extern OSStatus MIDISetupInstall( MIDISetupRef setup );
setup
- The MIDISetup object to install. Ownership of this object is transferred from the client to the system; the client must not dispose of this MIDISetup.
MIDISetupGetCurrent |
Return the system's current MIDISetup.
As of CoreMIDI 1.1, it is usually not necessary to call
this function, as CoreMIDI manages a single persistent
MIDISetup itself.
extern OSStatus MIDISetupGetCurrent( MIDISetupRef *outSetup );
outSetup
- On successful return, points to the system's most recently installed MIDISetup. The system retains ownership of the object; the client must not dispose of this MIDISetup.
MIDISetupToData |
Create an XML representation of a MIDISetup object.
As of CoreMIDI 1.1, it is usually not necessary to call
this function, as CoreMIDI manages a single persistent
MIDISetup itself.
extern OSStatus MIDISetupToData( MIDISetupRef setup, CFDataRef *outData );
setup
- The MIDISetup object whose XML representation is to be returned.
outData
- On successful return, points to a newly-created CFDataRef containing the XML text. The client is responsible for releasing this CFData object when done with it.
MIDISetupFromData |
Create a MIDISetup object from an XML stream.
As of CoreMIDI 1.1, it is usually not necessary to call
this function, as CoreMIDI manages a single persistent
MIDISetup itself.
extern OSStatus MIDISetupFromData( CFDataRef data, MIDISetupRef *outSetup);
data
- The XML text from which a MIDISetup object is to be built.
outSetup
- On successful return, points to a newly-created MIDISetup object. The caller is responsible for disposing it, or transferring ownership of the object back to the system, with MIDISetupInstall.
MIDIDeviceAddEntity |
extern OSStatus MIDIDeviceAddEntity( MIDIDeviceRef device, CFStringRef name, Boolean embedded, ItemCount numSourceEndpoints, ItemCount numDestinationEndpoints, MIDIEntityRef *newEntity) ;
device
- The device to which an entity is to be added.
name
- The name of the new entity.
embedded
- True if this entity is inside the device, false if the entity simply consists of external connectors to which other devices can be attached.
numSourceEndpoints
- The number of source endpoints the entity has.
numDestinationEndpoints
- The number of destination endpoints the entity has.
newEntity
- On successful return, points to the newly-created entity.
Drivers call this function to specify one of the entities that
comprise a device.
Non-drivers may call this function as of CoreMIDI 1.1, to
add entities to external devices.
MIDIDeviceRemoveEntity |
extern OSStatus MIDIDeviceRemoveEntity( MIDIDeviceRef device, MIDIEntityRef entity) ;
device
- The device from which an entity is to be removed.
entity
- The entity to be removed.
Drivers may call this function to remove one of a device's
entities.
New for CoreMIDI 1.1.
MIDIEntityAddOrRemoveEndpoints |
extern OSStatus MIDIEntityAddOrRemoveEndpoints( MIDIEntityRef entity, ItemCount numSourceEndpoints, ItemCount numDestinationEndpoints);
entity
- The entity whose endpoints are to be manipulated.
numSourceEndpoints
- The desired new number of source endpoints.
numDestinationEndpoints
- The desired new number of destination endpoints.
Drivers and configuration editors may call this function to add to
or remove an entity's endpoints.
New for CoreMIDI 1.3.
MIDISetupAddDevice |
Adds a driver-owner MIDI device to the current MIDISetup
extern OSStatus MIDISetupAddDevice( MIDIDeviceRef device );
device
- The device to be added.
Only MIDI drivers may make this call; it is in this header
file only for consistency with MIDISetupRemoveDevice.
New for CoreMIDI 1.1.
MIDISetupRemoveDevice |
Removes a driver-owned MIDI device from the current MIDISetup
extern OSStatus MIDISetupRemoveDevice( MIDIDeviceRef device );
device
- The device to be added.
Generally this should only be called from a studio configuration
editor, to remove a device which is offline and which the user
has specified as being permanently missing.
Instead of removing devices from the setup, drivers should
set the device's kMIDIPropertyOffline to 1 so that if the
device reappears later, none of its properties are lost.
New for CoreMIDI 1.1.
MIDISetupAddExternalDevice |
Adds an external MIDI device to the current MIDISetup
extern OSStatus MIDISetupAddExternalDevice( MIDIDeviceRef device );
device
- The device to be added.
Useful for a studio configuration editor. New for CoreMIDI 1.1.
MIDISetupRemoveExternalDevice |
Removes an external MIDI device from the current MIDISetup
extern OSStatus MIDISetupRemoveExternalDevice( MIDIDeviceRef device );
device
- The device to be removed.
Useful for a studio configuration editor. New for CoreMIDI 1.1.
MIDIGetSerialPortOwner |
Returns the MIDI driver that owns a serial port.
extern OSStatus MIDIGetSerialPortOwner( CFStringRef portName, CFStringRef *outDriverName );
portName
- The name of a serial port.
outDriverName
- On exit, the name of the driver owning the port, or NULL if no driver owns it.
The current MIDISetup tracks ownership of serial ports
to one of the MIDI drivers installed in the system.
Serial ports can be enumerated using IOServiceMatching(
kIOSerialBSDServiceValue). The port's unique name is
the IOService's kIOTTYDeviceKey property.
New for CoreMIDI 1.1.
A previous version of this documentation specified an incorrect
key for obtaining the port's unique name (IOTTYBaseName).
MIDISetSerialPortOwner |
Specifies the MIDI driver that owns a serial port.
extern OSStatus MIDISetSerialPortOwner( CFStringRef portName, CFStringRef driverName );
portName
- The name of a serial port.
driverName
- The name of the driver that owns the serial port, or NULL to specify that no driver owns it.
Use this to assign ownership of a serial port
to one of the MIDI drivers installed in the system.
New for CoreMIDI 1.1.
MIDIGetSerialPortDrivers |
Returns a list of installed MIDI drivers for serial port MIDI devices.
extern OSStatus MIDIGetSerialPortDrivers( CFArrayRef *outDriverNames );
outDriverNames
- On exit, a CFArrayRef containing a list of CFStringRef's which are the names of the serial port MIDI drivers. The array should be released by the caller.
Use this to determine which of the installed MIDI drivers
are for devices which may attach to serial ports.
New for CoreMIDI 1.1.
MIDIExternalDeviceCreate |
Create a new external MIDI device.
extern OSStatus MIDIExternalDeviceCreate( CFStringRef name, CFStringRef manufacturer, CFStringRef model, MIDIDeviceRef *outDevice) ;
name
- The name of the new device.
manufacturer
- The name of the device's manufacturer.
model
- The device's model name.
outDevice
- On successful return, points to the newly-created device.
Non-drivers may call this function as of CoreMIDI 1.1, to
create external devices.
The new device is not added to the current MIDISetupRef;
to do this, use MIDISetupAddExternalDevice.
MIDISetupRef |
typedef struct OpaqueMIDISetup * MIDISetupRef;
Derives from MIDIObjectRef, does not have an owner object.
This represents the global state of the MIDI system,
containing lists of the MIDI devices and serial port
owners.
Generally, only MIDI drivers and specialized configuration
editors will need to manipulate MIDISetup objects, not the
average MIDI client application. As of CoreMIDI 1.1, the
MIDIServer maintains a single global MIDISetupRef, stored
persistently in a preference file.
(Last Updated February 25, 2005)