MIDIThruConnection.h

Overview

This header defines functions to create MIDI play-through connections between the MIDI sources and destinations. These connections may be persistent or transitory, owned by a client.

By using connections instead of doing MIDI Thru operations themselves, the overhead of moving MIDI messages between the server and the client for thru-ing is reduced.

The aim of these functions is to permit as flexible a set of transformations as possible while keeping the API and data structures relatively simple.

Functions

MIDIThruConnectionCreate

Creates a thru connection.

MIDIThruConnectionDispose

Disposes a thru connection.

MIDIThruConnectionFind

Returns all of the persistent thru connections created by a client.

MIDIThruConnectionGetParams

Obtains a thru connection's MIDIThruConnectionParams.

MIDIThruConnectionParamsInitialize

Fills a MIDIThruConnectionParams with default values.

MIDIThruConnectionSetParams

Alters a thru connection's MIDIThruConnectionParams.

Creates a thru connection.

extern OSStatus MIDIThruConnectionCreate(
    CFStringRef inPersistentOwnerID, 
    CFDataRef inConnectionParams, 
    MIDIThruConnectionRef *outConnection ) ;  

Parameters

inPersistentOwnerID

If null, then the connection is marked as owned by the client and will be automatically disposed with the client. if it is non-null, then it should be a unique identifier, e.g. "com.mycompany.MyCoolProgram".

inConnectionParams

A MIDIThruConnectionParams contained in a CFDataRef.

outConnection

On successful return, a reference to the newly-create connection.

Return Value

An OSStatus result code.

Availability

Introduced in Mac OS X v10.2

Disposes a thru connection.

extern OSStatus MIDIThruConnectionDispose(
    MIDIThruConnectionRef connection ) ;  

Parameters

connection

The connection to be disposed

Return Value

An OSStatus result code.

Availability

Introduced in Mac OS X v10.2

Returns all of the persistent thru connections created by a client.

extern OSStatus MIDIThruConnectionFind(
    CFStringRef inPersistentOwnerID, 
    CFDataRef *outConnectionList ) ;  

Parameters

inPersistentOwnerID

The ID of the owner whose connections are to be returned.

outConnectionList

On successful return, a CFDataRef containing an array of MIDIThruConnectionRef's.

Return Value

An OSStatus result code.

Availability

Introduced in Mac OS X v10.2

Obtains a thru connection's MIDIThruConnectionParams.

extern OSStatus MIDIThruConnectionGetParams(
    MIDIThruConnectionRef connection, 
    CFDataRef *outConnectionParams ) ;  

Parameters

connection

The connection to be disposed.

outConnectionParams

On successful return, the connection's MIDIThruConnectionParams in a CFDataRef

Return Value

An OSStatus result code.

Discussion

The returned CFDataRef contains a MIDIThruConnectionParams structure. The caller is responsible for releasing it.

Availability

Introduced in Mac OS X v10.2

Fills a MIDIThruConnectionParams with default values.

extern void MIDIThruConnectionParamsInitialize( 
    MIDIThruConnectionParams *inConnectionParams ) ;  

Parameters

inConnectionParams

The struct to be initialized.

Return Value

An OSStatus result code.

Discussion

This convenience function fills the connection structure with default values: no endpoints, no transformations (mostly zeroes except for the channel map). Then, just filling in the source and adding one destination will create a simple, unmodified thru connection.

Availability

Introduced in Mac OS X v10.2

Alters a thru connection's MIDIThruConnectionParams.

extern OSStatus MIDIThruConnectionSetParams(
    MIDIThruConnectionRef connection, 
    CFDataRef inConnectionParams ) ;  

Parameters

connection

The connection to be modified.

inConnectionParams

The connection's new MIDIThruConnectionParams in a CFDataRef

Return Value

An OSStatus result code.

Availability

Introduced in Mac OS X v10.2

Typedefs

typedef MIDIObjectRef MIDIThruConnectionRef;  

Discussion

An opaque reference to a play-through connection.

Structs and Unions

Describes a transformation of MIDI control change events.

struct MIDIControlTransform { 
    MIDITransformControlType controlType; 
    MIDITransformControlType remappedControlType; 
    UInt16 controlNumber; 
    MIDITransformType transform; 
    SInt16 param; 
};  

Fields

controlType

The type of control specified by controlNumber

remappedControlType

If transform is kMIDITransform_MapControl, the output control type

controlNumber

The control number to be affected.

transform

The type of transformation to be applied to the event values.

param

An argument to the transformation method (see description of MIDITransformType).

Discussion

A single MIDIThruConnectionParams may describe any number of transformations to control events. It is important that multiple transformations are ordered correctly: filter out, remap, then alter values.

All transformations are done internally using 14-bit values, so for example, when doing an add/min/max transform on a 7-bit control value, the parameter must be a 14-bit value. For example, to add 10 to a control value, param must be (10 << 7) = 1280.

Describes a source or destination in a MIDIThruConnection.

struct MIDIThruConnectionEndpoint { 
    MIDIEndpointRef endpointRef; 
    MIDIUniqueID uniqueID; 
};  

Fields

endpointRef

The endpoint specified as a MIDIEndpointRef.

uniqueID

The endpoint specified by its uniqueID.

Discussion

When creating one of these, you can leave uniqueID 0 if the endpoint exists and you are passing its MIDIEndpointRef.

When obtaining one of these from CoreMIDI, endpointRef may be NULL if it doesn't exist, but the uniqueID will always be non-zero.

Describes a set of MIDI routings and transformations.

struct MIDIThruConnectionParams { 
    UInt32 version; 
    UInt32 numSources; 
    MIDIThruConnectionEndpoint sources[
            kMIDIThruConnection_MaxEndpoints]; 
    UInt32 numDestinations; 
    MIDIThruConnectionEndpoint destinations[
            kMIDIThruConnection_MaxEndpoints];  
    UInt8 channelMap[16]; 
    UInt8 lowVelocity, highVelocity; 
    UInt8 lowNote, highNote; 
    MIDITransform noteNumber; 
    MIDITransform velocity; 
    MIDITransform keyPressure; 
    MIDITransform channelPressure; 
    MIDITransform programChange; 
    MIDITransform pitchBend;  
    UInt8 filterOutSysEx; 
    UInt8 filterOutMTC; 
    UInt8 filterOutBeatClock; 
    UInt8 filterOutTuneRequest; 
    UInt8 reserved2[3]; 
    UInt8 filterOutAllControls;  
    UInt16 numControlTransforms; 
    UInt16 numMaps; 
    UInt16 reserved3[4];  
    // remainder of structure is variable-length: 
    // MIDIControlTransform controls[]; 
    // MIDIValueMap maps[]; 
};  

Fields

version

Version of this structure; must be 0.

numSources

The number of valid sources in the following array.

sources

All MIDI generated by these sources is routed into this connection for processing and distribution to destinations.

numDestinations

The number of valid destinations in the following array.

destinations

All MIDI output from the connection is routed to these destinations.

channelMap

Maps each of the source 16 MIDI channels to channel 0-15 (1-16) or 0xFF when MIDI from a channel is to be filtered out.

lowVelocity

Note events with a velocity less than this value are filtered out.

highVelocity

Note events with a velocity greater than this, if it is not 0, are filtered out.

lowNote

See highNote.

highNote

If highNote >= lowNote, then notes outside this range are filtered out. If lowNote > highNote, then notes inside this range are filtered out. This applies to note and polyphonic key pressure events. These fields are ignored if a there is a MIDIValueMap applying to noteNumber.

noteNumber

Specifies how MIDI note numbers are transformed.

velocity

Specifies how MIDI note velocities are transformed.

keyPressure

Specifies how MIDI polyphonic key pressure events are transformed.

channelPressure

Specifies how MIDI monophonic (channel) pressure events are transformed.

programChange

Specifies how MIDI program change events are transformed.

pitchBend

Specifies how MIDI pitch bend events are transformed.

filterOutSysEx

If 1, specifies that system-exclusive messages are to be filtered out.

filterOutMTC

If 1, specifies that MIDI Time Code messages are to be filtered out.

filterOutBeatClock

If 1, specifies the MIDI clock, play, stop, and resume messages are to be filtered out.

filterOutTuneRequest

If 1, specifies that MIDI Tune Request messages are to be filtered out.

reserved2

Must be 0.

filterOutAllControls

If 1, specifies that all MIDI continuous control messages are to be filtered out.

numControlTransforms

The number of control transformations in the variable-length portion of the struct.

numMaps

The number of MIDIValueMaps in the variable-length portion of the struct.

reserved3

Must be 0.

Discussion

The remainder of the structure is variably-sized. It contains numControlTransform instances of MIDIControlTransform, followed by numMaps instances of MIDIValueMap.

Describes how a single type of MIDI event is transformed.

struct MIDITransform { 
    MIDITransformType transform; 
    SInt16 param; 
};  

Fields

transform

The type of transformation to be applied to the event values.

param

An argument to the transformation method (see description of MIDITransformType).

Discussion

This structure controls the transformation of various MIDI events other than control changes.

struct MIDIValueMap { 
    UInt8 value[128]; 
};  

Discussion

A custom mapping function to transform MIDI 7-bit values, as contained in note numbers, velocities, control values, etc. y = value[x], where x is the input MIDI value, y the output.

Enumerations

enum { // MIDITransformControlType 
    kMIDIControlType_7Bit = 0, 
    kMIDIControlType_14Bit = 1, 
    kMIDIControlType_7BitRPN = 2, 
    kMIDIControlType_14BitRPN = 3, 
    kMIDIControlType_7BitNRPN = 4, 
    kMIDIControlType_14BitNRPN = 5 
};  

Constants

kMIDIControlType_7Bit

control numbers may be 0-127

kMIDIControlType_14Bit

control numbers may be 0-31

kMIDIControlType_7BitRPN

control numbers may be 0-16383

kMIDIControlType_14BitRPN

kMIDIControlType_7BitNRPN

kMIDIControlType_14BitNRPN

Discussion

Specifies how control numbers are interpreted.

enum { // MIDITransformType 
    kMIDITransform_None = 0, 
    kMIDITransform_FilterOut = 1, 
    kMIDITransform_MapControl = 2, 
    kMIDITransform_Add = 8, 
    kMIDITransform_Scale = 9, 
    kMIDITransform_MinValue = 10, 
    kMIDITransform_MaxValue = 11, 
    kMIDITransform_MapValue = 12 
};  

Constants

kMIDITransform_None

no transformation (param unused)

kMIDITransform_FilterOut

filter out the specified event type (param unused)

kMIDITransform_MapControl

transform one control number to another; param is destination control number

kMIDITransform_Add

add param to values

kMIDITransform_Scale

multiple value by the fixed point number in param, which is in fixed point: bbbb.bbbb bbbb bbbb

kMIDITransform_MinValue

the value's minimum value is param

kMIDITransform_MaxValue

the value's maximum value is param

kMIDITransform_MapValue

transform the value using a map; param is the index of the map in the connection's array of maps.

Discussion

Values specifying a type of MIDI transformation, as found in the transform member of MIDITransform.

#defines

Returns the size of a MIDIThruConnectionParams.

#define MIDIThruConnectionParamsSize(ptr) \ 
    (sizeof(MIDIThruConnectionParams) + (ptr)->numControlTransforms * sizeof(MIDIControlTransform) \ 
    + (ptr)->numMaps * sizeof(MIDIValueMap)) 

Discussion

Accounts for the variable-length elements in the structure and returns its true size in bytes.

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