MIDI Setup Reference

Contents

MIDI Setup Reference 3

Overview 3 Functions 3 MIDIDeviceAddEntity 3 MIDIDeviceRemoveEntity 4 MIDIEntityAddOrRemoveEndpoints 5 MIDIExternalDeviceCreate 5 MIDISetupAddDevice 6 MIDISetupAddExternalDevice 7 MIDISetupRemoveDevice 7 MIDISetupRemoveExternalDevice 8 Data Types 9 MIDISetupRef 9

Document Revision History 10

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

MIDI Setup Reference

Framework Declared in

CoreMIDI.framework MIDISetup.h

Overview
The functions described in this document let you manipulate and customize the global state of the MIDI system. These functions are usually needed only by apps that wish to allow the user some flexibility in how the MIDI systems state is presented.

Functions
MIDIDeviceAddEntity

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.

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

MIDI Setup Reference Functions

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 A 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 Available in iOS 4.2 and later. Declared in
MIDISetup.h

MIDIDeviceRemoveEntity

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 A result code. Discussion Drivers may call this function to remove one of a device's entities. New for CoreMIDI 1.1.

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

MIDI Setup Reference Functions

Availability Available in iOS 4.2 and later. Declared in

MIDISetup.h

MIDIEntityAddOrRemoveEndpoints

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 A 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 Available in iOS 4.2 and later. Declared in
MIDISetup.h

MIDIExternalDeviceCreate
Create a new external MIDI device.

OSStatus MIDIExternalDeviceCreate (

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

MIDI Setup Reference Functions

CFStringRef CFStringRef CFStringRef MIDIDeviceRef );

name, manufacturer, model, *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 A 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 Available in iOS 4.2 and later. Declared in
MIDISetup.h

MIDISetupAddDevice
Adds a driver-owner MIDI device to the current MIDISetup

OSStatus MIDISetupAddDevice ( MIDIDeviceRef device );

Parameters
device

The device to be added.

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

MIDI Setup Reference Functions

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 Available in iOS 4.2 and later. Declared in
MIDISetup.h

MIDISetupAddExternalDevice
Adds an external MIDI device to the current MIDISetup

OSStatus MIDISetupAddExternalDevice ( MIDIDeviceRef device );

Parameters
device

The device to be added. Discussion Useful for a studio configuration editor. New for CoreMIDI 1.1. Availability Available in iOS 4.2 and later. Declared in
MIDISetup.h

MIDISetupRemoveDevice
Removes a driver-owned MIDI device from the current MIDISetup

OSStatus MIDISetupRemoveDevice ( MIDIDeviceRef device );

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

MIDI Setup Reference Functions

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 Available in iOS 4.2 and later. Declared in
MIDISetup.h

MIDISetupRemoveExternalDevice
Removes an external MIDI device from the current MIDISetup

OSStatus MIDISetupRemoveExternalDevice ( MIDIDeviceRef device );

Parameters
device

The device to be removed. Discussion Useful for a studio configuration editor. New for CoreMIDI 1.1. Availability Available in iOS 4.2 and later. Declared in
MIDISetup.h

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

MIDI Setup Reference Data Types

Data Types
MIDISetupRef
The global state of the MIDI system, including lists of the MIDI devices and serial port owners.

#if __LP64__ typedef MIDIObjectRef MIDISetupRef; #else typedef struct OpaqueMIDISetup *MIDISetupRef; #endif

Discussion Derives from MIDIObjectRef, does not have an owner object. The MIDI server maintains a single global MIDISetupRef object, stored persistently in a preference file. Only specialized configuration editorsnot typical MIDI appsneed to manipulate MIDI setup objects. Availability Available in iOS 4.2 and later. Declared in
MIDISetup.h

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

Document Revision History

This table describes the changes to MIDI Setup Reference .

Date 2010-10-27

Notes New document that describes functions and data types for customizing the global state of the MIDI system.

2010-10-27 | 2010 Apple Inc. All Rights Reserved.

10

Apple Inc. 2010 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. The Apple logo is a trademark of Apple Inc. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple and the Apple logo are trademarks of Apple Inc., registered in the United States and other countries. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.