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

MIDISetup.h

Includes:

Overview

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.

Functions

MIDIDeviceAddEntity
MIDIDeviceRemoveEntity
MIDIEntityAddOrRemoveEndpoints
MIDIExternalDeviceCreate: Create a new external MIDI device.
MIDIGetSerialPortDrivers: Returns a list of installed MIDI drivers for serial port MIDI devices.
MIDIGetSerialPortOwner: Returns the MIDI driver that owns a serial port.
MIDISetSerialPortOwner: Specifies the MIDI driver that owns a serial port.
MIDISetupAddDevice: Adds a driver-owner MIDI device to the current MIDISetup
MIDISetupAddExternalDevice: Adds an external MIDI device to the current MIDISetup
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.
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.
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.
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.
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.
MIDISetupRemoveDevice: Removes a driver-owned MIDI device from the current MIDISetup
MIDISetupRemoveExternalDevice: Removes an external MIDI device from the current 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.

MIDIDeviceAddEntity

extern OSStatus MIDIDeviceAddEntity(
    MIDIDeviceRef device,
    CFStringRef name, 
    Boolean embedded,
    ItemCount numSourceEndpoints, 
    ItemCount numDestinationEndpoints,
    MIDIEntityRef *newEntity) ;

Parameters

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.

Return Value

An OSStatus result code.

Discussion

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.

Availability: Introduced in Mac OS X v10.0.

MIDIDeviceRemoveEntity

extern OSStatus MIDIDeviceRemoveEntity(
    MIDIDeviceRef device,
    MIDIEntityRef entity) ;

Parameters

device: The device from which an entity is to be removed.
entity: The entity to be removed.

Return Value

An OSStatus result code.

Discussion

Drivers may call this function to remove one of a device's entities.

New for CoreMIDI 1.1.

Availability: Introduced in Mac OS X v10.1.

MIDIEntityAddOrRemoveEndpoints

extern OSStatus MIDIEntityAddOrRemoveEndpoints(
    MIDIEntityRef entity,
    ItemCount numSourceEndpoints, 
    ItemCount numDestinationEndpoints);

Parameters

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.

Return Value

An OSStatus result code.

Discussion

Drivers and configuration editors may call this function to add to or remove an entity's endpoints.

New for CoreMIDI 1.3.

Availability: Introduced in Mac OS X v10.2

MIDIExternalDeviceCreate

Create a new external MIDI device.

extern OSStatus MIDIExternalDeviceCreate(
    CFStringRef name,
    CFStringRef manufacturer, 
    CFStringRef model,
    MIDIDeviceRef *outDevice) ;

Parameters

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.

Return Value

An OSStatus result code.

Discussion

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.

Availability: Introduced in Mac OS X v10.1.

MIDIGetSerialPortDrivers

Returns a list of installed MIDI drivers for serial port MIDI devices.

extern OSStatus MIDIGetSerialPortDrivers(
    CFArrayRef *outDriverNames );

Parameters

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.

Return Value

An OSStatus result code.

Discussion

Use this to determine which of the installed MIDI drivers are for devices which may attach to serial ports.

New for CoreMIDI 1.1.

Availability: Introduced in Mac OS X v10.1.

MIDIGetSerialPortOwner

Returns the MIDI driver that owns a serial port.

extern OSStatus MIDIGetSerialPortOwner(
    CFStringRef portName, 
    CFStringRef *outDriverName );

Parameters

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.

Return Value

An OSStatus result code.

Discussion

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).

Availability: Introduced in Mac OS X v10.1.

MIDISetSerialPortOwner

Specifies the MIDI driver that owns a serial port.

extern OSStatus MIDISetSerialPortOwner(
    CFStringRef portName, 
    CFStringRef driverName );

Parameters

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.

Return Value

An OSStatus result code.

Discussion

Use this to assign ownership of a serial port to one of the MIDI drivers installed in the system.

New for CoreMIDI 1.1.

Availability: Introduced in Mac OS X v10.1.

MIDISetupAddDevice

Adds a driver-owner MIDI device to the current MIDISetup

extern OSStatus MIDISetupAddDevice(
    MIDIDeviceRef device );

Parameters

device: The device to be added.

Discussion

Only MIDI drivers may make this call; it is in this header file only for consistency with MIDISetupRemoveDevice.

New for CoreMIDI 1.1.

Availability: Introduced in Mac OS X v10.1.

MIDISetupAddExternalDevice

Adds an external MIDI device to the current MIDISetup

extern OSStatus MIDISetupAddExternalDevice(
    MIDIDeviceRef device );

Parameters

device: The device to be added.

Discussion

Useful for a studio configuration editor. New for CoreMIDI 1.1.

Availability: Introduced in Mac OS X v10.1.

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 );

Parameters

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.

Return Value

An OSStatus result code.

Availability: Introduced in Mac OS X v10.0.

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 );

Parameters

setup: The MIDISetup to be disposed.

Return Value

An OSStatus result code.

Availability: Introduced in Mac OS X v10.0.

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);

Parameters

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.

Return Value

An OSStatus result code.

Availability: Introduced in Mac OS X v10.0.

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 );

Parameters

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.

Return Value

An OSStatus result code.

Availability: Introduced in Mac OS X v10.0.

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 );

Parameters

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.

Return Value

An OSStatus result code.

Availability: Introduced in Mac OS X v10.0.

MIDISetupRemoveDevice

Removes a driver-owned MIDI device from the current MIDISetup

extern OSStatus MIDISetupRemoveDevice(
    MIDIDeviceRef device );

Parameters

device: The device to be added.

Discussion

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.

Availability: Introduced in Mac OS X v10.1.

MIDISetupRemoveExternalDevice

Removes an external MIDI device from the current MIDISetup

extern OSStatus MIDISetupRemoveExternalDevice(
    MIDIDeviceRef device );

Parameters

device: The device to be removed.

Discussion

Useful for a studio configuration editor. New for CoreMIDI 1.1.

Availability: Introduced in Mac OS X v10.1.

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 );

Parameters

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.

Return Value

An OSStatus result code.

Availability: Introduced in Mac OS X v10.0.

Typedefs

MIDISetupRef

typedef MIDIObjectRef MIDISetupRef;

Discussion

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.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11