MIDIEnableInstance
The MIDIEnableInstance function activates or restores the transmission, reception, or both data streams of a specified MIDI logical node instance. This function handles the operational flow state of the node by adjusting its reference tracking constraints.
Syntax
#include <mididll.h> MINSTANCE minstance; /* Instance handle (Input) */ ULONG ulFlag; /* Direction flag (Input) */ ULONG rc; /* Return code */ rc = MIDIEnableInstance(minstance, ulFlag);
Parameters
- minstance (MINSTANCE) - input
- The specific tracking identification handle of the logical node instance to be activated.
- ulFlag (ULONG) - input
- Flag configuration determining which data direction pipeline to enable. It must be set to one or a bitwise combination of the following identifiers:
- MIDI_ENABLE_SEND: Activates the node instance to allow broadcasting or transmitting outbound MIDI messages.
- MIDI_ENABLE_RECEIVE: Activates the node instance to allow listening to or capturing inbound MIDI messages.
Return Value
- rc (ULONG) - returns
- Returns `0` (or `MIDI_SUCCESS`) if the target pipeline direction was brought online cleanly, or one of the following diagnostic error codes:
- MIDIERR_HARDWARE_FAILED: The initialization sequence failed because an underlying physical multimedia component or Type A device driver rejected the setup request or 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 enable outbound transmission on a node that natively operates exclusively as a receiver.
- MIDIERR_RESOURCE_NOT_AVAILABLE: The subsystem cannot allocate memory pools, tracking handles, or internal reference structures required to scale the pipeline.
- MIDIERR_SENDONLY: A validation failure indicating that the caller attempted to enable inbound reception on a node that natively operates exclusively as a transmitter.
Remarks
- Reference Counting Infrastructure: Outbound transmission paths and inbound reception paths are managed independently using distinct **reference counters**. Invoking MIDIEnableInstance increments the tracking count for the specified direction. This architecture allows multiple links or client routines to share an instance stream concurrently without causing premature deactivation collisions.
- Default Node State Divergence:
- Standard / Software Nodes: All software and client filter nodes are initialized as **enabled by default** when generated via MIDICreateInstance.
- Hardware Nodes: Physical components mapped to physical audio equipment interfaces are initialized as **disabled by default** to preserve system memory and power. The first successful call to activate a hardware node instructs the subsystem to issue an explicit open call to the corresponding Type A device driver. If the driver fails this request, the subsystem drops the state and yields `MIDIERR_HARDWARE_FAILED`.
- Direction Over-Specification Pitfalls: If an application requests to enable a direction that contradicts the physical capabilities of a unidirectional node, the request is completely rejected, leaving both directions unassigned. For example, passing a combined flag to a send-only node yields a `MIDIERR_SENDONLY` failure and does not activate transmission.
- Asymmetric Activation Risks: Attempting to enable both directions simultaneously in a single command can introduce ambiguous system states. If one path fails to initialize (common during physical driver component collisions or when a reference ceiling is breached), 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 activations into separate, sequential calls to MIDIEnableInstance.