MIDISetup Reference

7/31/2019 MIDISetup Reference

1/11

MIDI Setup Reference


2/11

Contents

MIDI Setup Reference 3

Overview 3

Functions 3

MIDIDeviceAddEntity 3

MIDIDeviceRemoveEntity 4

MIDIEntityAddOrRemoveEndpoints 5

MIDIExternalDeviceCreate 5

MIDISetupAddDevice 6

MIDISetupAddExternalDevice 7MIDISetupRemoveDevice 7

MIDISetupRemoveExternalDevice 8

Data Types 9

MIDISetupRef 9

Document Revision History 10

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

2


3/11

Framework CoreMIDI.framework

Declared in MIDISetup.h

OverviewThe functions describedin this document letyou manipulate and customizethe 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.


3



4/11

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.


Functions


4


5/11

Availability


Declared in

MIDISetup.h

MIDIEntityAddOrRemoveEndpoints

OSStatus MIDIEntityAddOrRemoveEndpoints (

MIDIEntityRef entity,

ItemCount numSourceEndpoints,

ItemCount numDestinationEndpoints

);

Parametersentity

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.


Availability


Declared in

MIDISetup.h

MIDIExternalDeviceCreate

Create a new external MIDI device.

OSStatus MIDIExternalDeviceCreate (


Functions


5


6/11

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

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


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.


Functions


6


7/11

Discussion

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


AvailabilityAvailable in iOS 4.2 and later.

Declared in

MIDISetup.h

MIDISetupAddExternalDevice

Adds an external MIDI device to the current MIDISetup

OSStatus MIDISetupAddExternalDevice (


);

Parameters

device


Discussion

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

Availability


Declared in

MIDISetup.h

MIDISetupRemoveDevice

Removes a driver-owned MIDI device from the current MIDISetup

OSStatus MIDISetupRemoveDevice (


);


Functions


7


8/11

Parameters

device


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


Availability


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


Declared in

MIDISetup.h


Functions


8


9/11


10/11

This table describes the changes to MIDI Setup Reference .

NotesDate

New document that describes functions and data types for customizing

the global state of the MIDI system.

2010-10-27


10

Document Revision History


11/11

Apple Inc.

2010 Apple Inc.

All rights reserved.

No part of this publication may be reproduced,

storedin a retrievalsystem, 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 herebyauthorized to store documentation on a single

computer for personal use only and to print

copies of documentation for personal useprovided that the documentation contains

Apples copyright notice.

The Apple logo is a trademark of Apple Inc.

No licenses, express or implied, are granted withrespect to anyof thetechnology describedin this

document. Apple retains all intellectual property

rights associated with the technology describedin this document. This document is intended to

assist application developers to develop

applications only for Apple-labeled computers.

Apple Inc.

1 Infinite LoopCupertino, 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 usedunder license.

Even though Apple has reviewed this document,

APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED,WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT,THIS DOCUMENT IS PROVIDEDAS IS, AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL,INCIDENTAL,OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension,or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation or

exclusion may not apply to you. This warranty givesyou specific legal rights, andyou mayalsohaveotherrights which vary from state to state.

Documents

MIDISetup Reference