MIKMIDIConnectionManager

Objective-C

@interface MIKMIDIConnectionManager : NSObject

Swift

class MIKMIDIConnectionManager : NSObject

MIKMIDIConnectionManager can be used to manage a set of connected devices. It can be configured to automatically connect to devices as they are added, and disconnect from them as they are removed. It also supports saving the list of connected to NSUserDefaults and restoring them upon relaunch.

The use of MIKMIDIConnectionManager is optional. It is meant to be useful in implementing functionality that many MIDI device enabled apps need. However, simple connection to devices or MIDI endpoints can be done with MIKMIDIDeviceManager directly, if desired.

  • Unavailable

    This method will throw an exception if called. Use -initWithName:delegate:eventHandler: instead.

    Declaration

    Objective-C

    - (nonnull instancetype)init;

    Return Value

    nil

  • Initializes an instance of MIKMIDIConnectionManager. The passed in name is used to independently store and load the connection manager’s configuration using NSUserDefaults. The passed in name should be unique across your application, and the same from launch to launch.

    Declaration

    Objective-C

    - (nonnull instancetype)
    initWithName:(nonnull NSString *)name
        delegate:(nullable id<MIKMIDIConnectionManagerDelegate>)delegate
    eventHandler:(nullable MIKMIDIEventHandlerBlock)eventHandler;

    Swift

    init(name: String, delegate: MIKMIDIConnectionManagerDelegate?, eventHandler: MIKMIDIEventHandlerBlock? = nil)

    Parameters

    name

    The name to give the connection manager. Must not be nil or empty.
    delegate

    The delegate of the connection manager
    eventHandler

    An MIKMIDIEventHandlerBlock to be called with incoming MIDI messages from any connected device.

    Return Value

    An initialized MIKMIDIConnectionManager instance.

  • Initializes an instance of MIKMIDIConnectionManager. The passed in name is used to independently store and load the connection manager’s configuration using NSUserDefaults. The passed in name should be unique across your application, and the same from launch to launch. This is the same as calling -initWithName:delegate:eventHandler: with a nil delegate and eventHandler.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithName:(nonnull NSString *)name;

    Swift

    convenience init(name: String)

    Parameters

    name

    The name to give the connection manager. Must not be nil or empty.

    Return Value

    An initialized MIKMIDIConnectionManager instance.

  • Connect to the specified device. When MIDI messages are received, the connection manager’s event handler block will be executed.

    Declaration

    Objective-C

    - (BOOL)connectToDevice:(nonnull MIKMIDIDevice *)device
                  error:(NSError *_Nullable *_Nullable)error;

    Swift

    func connect(to device: MIKMIDIDevice) throws

    Parameters

    device

    An MIKMIDIDevice instance.
    error

    If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    YES if the connection was successful, NO if an error occurred.

  • Disconnect from a connected device. No further messages from the specified device will be processed.

    Note that you don’t need to call this method when a previously-connected device was removed from the system. Disconnection in that situation is handled automatically.

    Declaration

    Objective-C

    - (void)disconnectFromDevice:(nonnull MIKMIDIDevice *)device;

    Swift

    func disconnect(from device: MIKMIDIDevice)

    Parameters

    device

    An MIKMIDIDevice instance.

  • This method can be used to determine if the receiver is connected to a given MIDI device.

    Declaration

    Objective-C

    - (BOOL)isConnectedToDevice:(nonnull MIKMIDIDevice *)device;

    Swift

    func isConnected(to device: MIKMIDIDevice) -> Bool

    Parameters

    device

    An MIKMIDIDevice instance.

    Return Value

    YES if the receiver is connected to and processing MIDI input from the device, NO otherwise.

  • If YES (the default), the connection manager will automatically save its configuration at appropriate times. If this property is NO, -saveConfiguration can still be used to manually trigger saving the receiver’s configuration. Note that -loadConfiguration must always be called manually, e.g. at launch.

    Declaration

    Objective-C

    @property (nonatomic) BOOL automaticallySavesConfiguration;

    Swift

    var automaticallySavesConfiguration: Bool { get set }

  • Save the receiver’s list of connected devices to disk for later restoration.

    Declaration

    Objective-C

    - (void)saveConfiguration;

    Swift

    func saveConfiguration()

  • Load and reconnect to the devices previously saved to disk by a call to -saveConfiguration. For this to work, the receiver’s name must be the same as it was upon the previous call to -saveConfiguration.

    @note: This method will only connect to new devices. It will not disconnect from devices not found in the saved configuration.

    Declaration

    Objective-C

    - (void)loadConfiguration;

    Swift

    func loadConfiguration()

  • The name of the receiver. Used for configuration save/load.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull name;

    Swift

    var name: String { get }

  • An MIKMIDIEventHandlerBlock to be called with incoming MIDI messages from any connected device.

    If you need to determine which device sent the passed in messages, call source.entity.device on the passed in MIKMIDISourceEndpoint argument.

    Declaration

    Objective-C

    @property (nonatomic, copy, null_resettable) MIKMIDIEventHandlerBlock eventHandler;

    Swift

    var eventHandler: MIKMIDIEventHandlerBlock! { get set }

  • A delegate, used to customize MIKMIDIConnectionManager behavior.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<MIKMIDIConnectionManagerDelegate> delegate;

    Swift

    weak var delegate: MIKMIDIConnectionManagerDelegate? { get set }

  • Controls whether the receiver’s availableDevices property includes virtual devices (i.e. devices made up of automatically paired virtual sources and destinations).

    If this property is YES (the default), the connection manager will attempt to automtically related associated virtual sources and destinations and create “virtual” MIKMIDIDevice instances for them.

    If this property is NO, the connection manager’s availableDevices array will only contain non-virtual MIKMIDIDevices.

    For most applications, this should be left at the default YES, as even many physical MIDI devices present as “virtual” devices in software.

    @note: The caveat here is that this relies on some heuristics to match up source endpoints with destination endpoints. These heuristics are based on the way certain common MIDI devices behave, but may not be universal, and therefore may miss, or fail to properly associate endpoints for some devices. If this is a problem for your application, you should obtain and connect to virtual sources/endpoints using MIKMIDIDeviceManager directly instead.

    Declaration

    Objective-C

    @property (nonatomic) BOOL includesVirtualDevices;

    Swift

    var includesVirtualDevices: Bool { get set }

  • An array of available MIDI devices.

    This property is observable using Key Value Observing.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSArray<MIKMIDIDevice *> *_Nonnull availableDevices;

    Swift

    var availableDevices: [MIKMIDIDevice] { get }

  • The set of MIDI devices to which the receiver is connected.

    This property is observable using Key Value Observing.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSSet<MIKMIDIDevice *> *_Nonnull connectedDevices;

    Swift

    var connectedDevices: Set<AnyHashable> { get }