MIKMIDICommand

Objective-C

@interface MIKMIDICommand : NSObject <NSCopying>

Swift

class MIKMIDICommand : NSObject, NSCopying

In MIKMIDI, MIDI messages are objects. Specifically, they are instances of MIKMIDICommand or one of its subclasses. MIKMIDICommand’s subclasses each represent a specific type of MIDI message, for example, control change command messages will be instances of MIKMIDIControlChangeCommand. MIKMIDICommand includes properties for getting information and data common to all MIDI messages. Its subclasses implement additional method and properties specific to messages of their associated type.

MIKMIDICommand is also available in mutable variants, most useful for creating commands to be sent out by your application.

To create a new command, typically, you should use +commandForCommandType:.

Subclass MIKMIDICommand

Support for the various MIDI message types is provided by type-specific subclasses of MIKMIDICommand. For example, Control Change messages are represented using MIKMIDIControlChangeCommand. MIKMIDI includes a limited number of MIKMIDICommand subclasses to support the most common MIDI message types. To support a new command type, you should create a new subclass of MIKMIDICommand (and please consider contributing it to the main MIKMIDI repository!). If you implement this subclass according to the rules explained below, it will automatically be used to represent incoming MIDI commands matching its MIDI command type.

To successfully subclass MIKMIDICommand, you must override at least the following methods:

+supportedMIDICommandTypes: - Return an array of one or more MIKMIDICommandTypes that your subclass supports.
+immutableCounterPartClass - Return the subclass itself (eg. return [MIKMIDINewTypeCommand class];)
+mutableCounterPartClass - Return the mutable counterpart class (eg. return [MIKMIDIMutableNewTypeCommand class;])

Optionally, override -additionalCommandDescription to provide an additional, type-specific description string.

You must also implement +load and call [MIKMIDICommand registerSubclass:self] to register your subclass with the MIKMIDICommand machinery.

When creating a subclass of MIKMIDICommand, you should also create a mutable variant which is itself a subclass of your type-specific MIKMIDICommand subclass. The mutable subclass should override +isMutable and return YES.

If your subclass adds additional properties, beyond those supported by MIKMIDICommand itself, those properties should only be settable on instances of the mutable variant class. The preferred way to accomplish this is to implement the setters on the immutable, base subclass. In their implementations, check to see if self is mutable, and if not, raise an exception. Use the following line of code:

    if (![[self class] isMutable]) return MIKMIDI_RAISE_MUTATION_ATTEMPT_EXCEPTION;

For a straightforward example of a MIKMIDICommand subclass, see MIKMIDINoteOnCommand.


                    
                    
                    +commandWithMIDIPacket:

Convenience method for creating a new MIKMIDICommand instance from a MIDIPacket as received or created using CoreMIDI functions. For command types for which there is a specific MIKMIDICommand subclass, an instance of the appropriate subclass will be returned.

Note

This method is used by MIKMIDI’s internal machinery, and its use by MIKMIDI clients, while not disallowed, is not typical. Normally, +commandForCommandType: should be used.

See

+commandForCommandType:

Declaration

Objective-C

+ (nonnull instancetype)commandWithMIDIPacket:(MIDIPacket *_Nullable)packet;

Swift

convenience init(midiPacket packet: UnsafeMutablePointer<MIDIPacket>?)

Parameters


                                packet

A pointer to an MIDIPacket struct.

Return Value

For supported command types, an initialized MIKMIDICommand subclass. Otherwise, an instance of MIKMIDICommand itself. nil if there is an error.


                    
                    
                    +commandsWithMIDIPacket:

Note

This method is used by MIKMIDI’s internal machinery, and its use by MIKMIDI clients, while not disallowed, is not typical. Normally, +commandForCommandType: should be used.

See

+commandForCommandType:

Declaration

Objective-C

+ (nonnull NSArray<MIKMIDICommand *> *)commandsWithMIDIPacket:
    (nonnull MIDIPacket *)packet;

Swift

class func commands(with packet: UnsafeMutablePointer<MIDIPacket>) -> [MIKMIDICommand]

Parameters


                                packet

A pointer to an MIDIPacket struct.

Return Value

An NSArray containing initialized MIKMIDICommand subclass instances for each MIDI message of a supported command type. For unsupported command types, an instance of MIKMIDICommand itself will be used. Returns nil if there is an error.


                    
                    
                    +commandForCommandType:

Convenience method for creating a new MIKMIDICommand. For command types for which there is a specific MIKMIDICommand subclass, an instance of the appropriate subclass will be returned.

Declaration

Objective-C

+ (nonnull __kindof instancetype)commandForCommandType:
    (MIKMIDICommandType)commandType;

Swift

class func command(for commandType: MIKMIDICommandType) -> Any

Parameters


                                commandType

The type of MIDI command to create. See MIKMIDICommandType for a list of possible values.

Return Value

For supported command types, an initialized MIKMIDICommand subclass. Otherwise, an instance of MIKMIDICommand itself. nil if there is an error.


                    
                    
                    -isEqualToCommand:

Returns a boolean value that indicates whether the receiver is equal to another command. Compares command type, timestamp, and raw data to determine if the two commands are equal.

Declaration

Objective-C

- (BOOL)isEqualToCommand:(nonnull MIKMIDICommand *)command;

Swift

func isEqual(to command: MIKMIDICommand) -> Bool

Parameters


                                command

The command with which to compare the receiver.

Return Value

YES if command is equivalent to the receiver, otherwise NO.

timestamp
The time at which the MIDI message was received. Will be set for commands received from a connected MIDI source. For commands to be sent (ie. created by the MIKMIDI-using application), this must be set manually.
Declaration
Objective-C

@property (nonatomic, strong, readonly) NSDate *_Nonnull timestamp;
Swift

var timestamp: Date { get }
commandType
The receiver’s command type. See MIKMIDICommandType for a list of possible values.
Declaration
Objective-C

@property (nonatomic, readonly) MIKMIDICommandType commandType;
Swift

var commandType: MIKMIDICommandType { get }
statusByte
The MIDI status byte. The exact meaning of the contents of this byte differ for different command types. See http://www.midi.org/techspecs/midimessages.php for a information about the contents of this value.
Declaration
Objective-C

@property (nonatomic, readonly) UInt8 statusByte;
Swift

var statusByte: UInt8 { get }
dataByte1
The first byte of the MIDI data (after the command type).
Declaration
Objective-C

@property (nonatomic, readonly) UInt8 dataByte1;
Swift

var dataByte1: UInt8 { get }
dataByte2
The second byte of the MIDI data (after the command type).
Declaration
Objective-C

@property (nonatomic, readonly) UInt8 dataByte2;
Swift

var dataByte2: UInt8 { get }
midiTimestamp
The timestamp for the receiver, expressed as a host clock time. This is the timestamp used by CoreMIDI. Usually the timestamp property, which returns an NSDate, will be more useful.

See
-timestamp
Declaration
Objective-C

@property (nonatomic, readonly) MIDITimeStamp midiTimestamp;
Swift

var midiTimestamp: MIDITimeStamp { get }


                    
                    
                    data

The raw data that makes up the receiver.

Declaration

Objective-C

@property (nonatomic, copy, readonly, null_resettable) NSData *data;

Swift

var data: Data! { get }

mappingItem
Optional mapping item used to route the command. This must be set by client code that handles receiving MIDI commands. Allows responders to understand how a command was mapped, especially useful to determine interaction type so that responders can interpret the command correctly.
Declaration
Objective-C

@property (nonatomic, strong, nullable) MIKMIDIMappingItem *mappingItem;
Swift

var mappingItem: MIKMIDIMappingItem? { get set }

MIKMIDIChannelEventToCommands


                    
                    
                    +commandFromChannelEvent:clock:

This is currently undocumented. Documentation contributions are always welcome!

Declaration

Objective-C

+ (nullable instancetype)commandFromChannelEvent:(MIKMIDIChannelEvent *)event clock:(MIKMIDIClock *)clock;

Swift

convenience init?(from event: MIKMIDIChannelEvent, clock: MIKMIDIClock)

MIKMIDIEventToCommands


                    
                    
                    +commandsFromMIDIEvent:clock:

This is currently undocumented. Documentation contributions are always welcome!

Declaration

Objective-C

+ (MIKArrayOf(MIKMIDICommand *) *)commandsFromMIDIEvent:(MIKMIDIEvent *)event clock:(nullable MIKMIDIClock *)clock;

Swift

class func commands(from event: MIKMIDIEvent, clock: MIKMIDIClock?) -> [MIKMIDICommand]

MIKMIDINoteEventToCommands


                    
                    
                    +commandsFromNoteEvent:clock:

Creates an MIKMIDINoteOnCommand and MIKMIDINoteOffCommand from an MIKMIDINoteEvent.

Declaration

Objective-C

+ (nonnull NSArray<MIKMIDICommand *> *)
    commandsFromNoteEvent:(nonnull MIKMIDINoteEvent *)noteEvent
                    clock:(nullable MIKMIDIClock *)clock;

Swift

class func commands(from noteEvent: MIKMIDINoteEvent, clock: MIKMIDIClock?) -> [MIKMIDICommand]

Parameters

`noteEvent`	A MIKMIDINoteEvent instance.
`clock`	An MIKMIDIClock instance used to convert from the note event’s sequence timestamp to a realtime MIDI time stamp. If clock is nil, the noteEvent’s timestamp is ignored, and its duration is assumed to be a quarter note at the default MIDI tempo of 120 BPM.


                    
                    
                    +noteOnCommandFromNoteEvent:clock:

This is currently undocumented. Documentation contributions are always welcome!

Declaration

Objective-C

+ (MIKMIDINoteOnCommand *)noteOnCommandFromNoteEvent:(MIKMIDINoteEvent *)noteEvent clock:(nullable MIKMIDIClock *)clock;

Swift

class func noteOnCommand(from noteEvent: MIKMIDINoteEvent, clock: MIKMIDIClock?) -> MIKMIDINoteOnCommand


                    
                    
                    +noteOffCommandFromNoteEvent:clock:

This is currently undocumented. Documentation contributions are always welcome!

Declaration

Objective-C

+ (MIKMIDINoteOffCommand *)noteOffCommandFromNoteEvent:(MIKMIDINoteEvent *)noteEvent clock:(nullable MIKMIDIClock *)clock;

Swift

class func noteOffCommand(from noteEvent: MIKMIDINoteEvent, clock: MIKMIDIClock?) -> MIKMIDINoteOffCommand