MIDIDisableInstance
The MIDIDisableInstance function mutes or halts the transmission, reception, or both data streams of a specified MIDI logical node instance. This function acts upon the operational flow of the node without completely removing or destroying the instance from the subsystem matrix.
Syntax
#include <mididll.h> MINSTANCE minstance; /* Instance handle (Input) */ ULONG ulFlag; /* Direction flag (Input) */ ULONG rc; /* Return code */ rc = MIDIDisableInstance(minstance, ulFlag);
Parameters
- minstance (MINSTANCE) - input
- The specific tracking identification handle of the logical node instance to be disabled.
- ulFlag (ULONG) - input
- Flag configuration determining which data direction pipeline to disable. It must be set to one or a bitwise combination of the following identifiers:
- MIDI_DISABLE_SEND: Disables the node instance from broadcasting or transmitting outbound MIDI messages.
- MIDI_DISABLE_RECEIVE: Disables the node instance from listening to or capturing inbound MIDI messages.
Return Value
- rc (ULONG) - returns
- Returns `0` (or `MIDI_SUCCESS`) if the target pipeline direction was shut down cleanly, or one of the following diagnostic error codes:
- MIDIERR_HARDWARE_FAILED: The shutdown sequence failed because an underlying physical multimedia component or Type A device driver encountered an unrecoverable hardware fault.
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal subsystem or system communication error occurred.
- MIDIERR_INVALID_FLAG: The value passed into the ulFlag parameter does not correspond to valid direction flags.
- MIDIERR_INVALID_INSTANCE_NUMBER: The instance handle provided in the minstance parameter is invalid, unregistered, or has expired.
- MIDIERR_NOT_ALLOWED: A directional configuration exception occurred, indicating that the targeted instance does not support dual-direction configurations or lacks both capabilities entirely.
- MIDIERR_RECEIVEONLY: A validation failure indicating that the caller attempted to disable outbound transmission on a node that natively operates exclusively as a receiver.
- MIDIERR_SENDONLY: A validation failure indicating that the caller attempted to disable inbound reception on a node that natively operates exclusively as a transmitter.
Remarks
- Reference Counting Infrastructure: Disabling a routing direction does not automatically flip an absolute off switch. Instead, the MIDI subsystem decrements a specialized direction-specific reference counter. The node's chosen communication path is only truly deactivated when this tracking value hits exactly `0`.
- Hardware Lifecycle Hooks (Type A Drivers): For static hardware-mapped nodes, a reference count drop to `0` triggers a physical down-state transition. The subsystem issues an explicit close call to the corresponding Type A device driver. If the hardware layer rejects this instruction, the subsystem returns `MIDIERR_HARDWARE_FAILED`, halts the teardown loop, and restores the reference tracking count back to `1`.
- Direction Over-Specification Pitfalls: If an application requests to disable a direction that contradicts the physical capabilities of a unidirectional node, the request is completely rejected, leaving the active direction running. For example, passing a combined flag to a send-only node yields a `MIDIERR_SENDONLY` failure and does not alter the transmission state.
- Asymmetric Failure Risks: Attempting to disable both directions simultaneously in a single command can introduce ambiguous system states. If one path fails to shut down (common during physical driver component collisions), the overall function throws an error, but one of the pipelines may remain running with no clear mechanism for the application to poll which side failed.
- To avoid ambiguous states, it is highly recommended to decouple multi-directional deactivations into separate, sequential calls to MIDIDisableInstance.