Inherits from NSObject
Conforms to NSCopying
Declared in MIKMIDICommand.h

Overview

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.

These methods can be called and/or overridden by subclasses of MIKMIDICommand, but are not otherwise part of the public interface to MIKMIDICommand. They should not be called directly except by subclasses of MIKMIDICommand.

Tasks

Other Methods

  • + 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.

  • + commandsWithMIDIPacket:

    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.

  • + 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.

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

    property
  •   commandType

    The receiver’s command type. See MIKMIDICommandType for a list of possible values.

    property
  •   dataByte1

    The first byte of the MIDI data (after the command type).

    property
  •   dataByte2

    The second byte of the MIDI data (after the command type).

    property
  •   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.

    property
  •   data

    The raw data that makes up the receiver.

    property
  •   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.

    property

Extension Methods

Properties

commandType

@property (nonatomic, readonly) MIKMIDICommandType commandType
Discussion

The receiver’s command type. See MIKMIDICommandType for a list of possible values.

Declared In

MIKMIDICommand.h

data

@property (nonatomic, copy, readonly) NSData *data
Discussion

The raw data that makes up the receiver.

Declared In

MIKMIDICommand.h

dataByte1

@property (nonatomic, readonly) UInt8 dataByte1
Discussion

The first byte of the MIDI data (after the command type).

Declared In

MIKMIDICommand.h

dataByte2

@property (nonatomic, readonly) UInt8 dataByte2
Discussion

The second byte of the MIDI data (after the command type).

Declared In

MIKMIDICommand.h

internalData

@property (nonatomic, strong, readwrite) NSMutableData *internalData
Discussion

This is the property used internally by MIKMIDICommand to store the raw data for a MIDI packet. It is essentially the mutable backing store for MIKMIDICommand’s data property. Subclasses may set it. When mutating it, subclasses should manually call -will/didChangeValueForKey for the data key path.

Declared In

MIKMIDICommand_SubclassMethods.h

mappingItem

@property (nonatomic, strong) MIKMIDIMappingItem *mappingItem
Discussion

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.

Declared In

MIKMIDICommand.h

midiTimestamp

@property (nonatomic, readonly) MIDITimeStamp midiTimestamp
Discussion

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.

Declared In

MIKMIDICommand.h

timestamp

@property (nonatomic, strong, readonly) NSDate *timestamp
Discussion

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.

Declared In

MIKMIDICommand.h

Class Methods

commandForCommandType:

+ (instancetype)commandForCommandType:(MIKMIDICommandType)commandType
Discussion

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.

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.

Declared In

MIKMIDICommand.h

commandWithMIDIPacket:

+ (instancetype)commandWithMIDIPacket:(MIDIPacket *)packet
Discussion

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.

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.

Declared In

MIKMIDICommand.h

commandsWithMIDIPacket:

+ (NSArray *)commandsWithMIDIPacket:(MIDIPacket *)packet
Discussion

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.

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.

Declared In

MIKMIDICommand.h

immutableCounterpartClass

+ (Class)immutableCounterpartClass
Discussion

The immutable counterpart class of the receiver.

Return Value

A class object for the immutable counterpart class of the receiver, or self if the receiver is the immutable class in the pair.

Declared In

MIKMIDICommand_SubclassMethods.h

isMutable

+ (BOOL)isMutable
Discussion

Mutable subclasses of MIKMIDICommand must override this method and return YES. MIKMIDICommand itself implements this and returns NO, so immutable subclasses need not override this method.

Return Value

YES if the receiver is a mutable MIKMIDICommand subclass, NO otherwise.

Declared In

MIKMIDICommand_SubclassMethods.h

mutableCounterpartClass

+ (Class)mutableCounterpartClass
Discussion

The mutable counterpart class of the receiver.

Return Value

A class object for the mutable counterpart class of the receiver, or self if the receiver is the mutable class in the pair.

Declared In

MIKMIDICommand_SubclassMethods.h

registerSubclass:

+ (void)registerSubclass:(Class)subclass
Discussion

Registers a subclass of MIKMIDICommand. Registered subclasses will be instantiated and returned by [MIKMIDICommand commandWithMIDIPacket:] and [MIKMIDICommand commandForCommandType:] for commands they support.

Typically this method should be called in the subclass’s +load method.

Note: If two subclasses support the same command type, as determined by calling supportedMIDICommandTypes which one is used is undefined.

Parameters

subclass

A subclass of MIKMIDICommand.

Declared In

MIKMIDICommand_SubclassMethods.h

supportedMIDICommandTypes

+ (NSArray *)supportedMIDICommandTypes
Discussion

Subclasses of MIKMIDICommand must override this method, and return the MIKMIDICommandType values they support. MIKMIDICommand uses this method to determine which subclass to use to represent a particular MIDI command type.

Note that the older supportsMIDICommandType: by default simply calls through to this method.

Return Value

An NSArray containing NSNumber instances containing MIKMIDICommandType values.

Declared In

MIKMIDICommand_SubclassMethods.h

supportsMIDICommandType:

+ (BOOL)supportsMIDICommandType:(MIKMIDICommandType)type
Discussion

This method has been replaced by supportedMIDICommandTypes and by default simply calls through to that method. Subclasses no longer need implement this.

Parameters

type

An MIKMIDICommandType value.

Return Value

YES if the subclass supports type, NO otherwise.

Declared In

MIKMIDICommand_SubclassMethods.h

Instance Methods

additionalCommandDescription

- (NSString *)additionalCommandDescription
Discussion

Additional description string to be appended to basic description provided by [MIKMIDICommand description]. Subclasses of MIKMIDICommand can override this to provide a additional description information.

Return Value

A string to be appended to MIKMIDICommand’s basic description.

Declared In

MIKMIDICommand_SubclassMethods.h

initWithMIDIPacket:

- (id)initWithMIDIPacket:(MIDIPacket *)packet
Discussion

This is provided for subclasses to override. This is the designated initializer for MIKMIDICommand. For commands created using [MIKMIDICommand commandForCommandType:], the packet argument will be NULL.

Parameters

packet

A CoreMIDI MIDIPacket pointer. May be NULL.

Return Value

An initialized MIKMIDICommand (or subclass) instance.

Declared In

MIKMIDICommand_SubclassMethods.h