MIDIDeleteInstance
The MIDIDeleteInstance function destroys a previously created logical MIDI node instance, removing it from the system's active MIDI connection matrix and freeing its allocated tracking structures.
Syntax
#include <mididll.h> MINSTANCE minstance; /* Instance handle (Input) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDIDeleteInstance(minstance, ulFlag);
Parameters
- minstance (MINSTANCE) - input
- The distinct tracking identification handle of the logical node instance that needs to be torn down and destroyed.
- ulFlag (ULONG) - input
- A reserved subsystem flag parameter. This must be explicitly set to `0`.
Return Value
- rc (ULONG) - returns
- Returns `0` (or `MIDI_SUCCESS`) if the instance is unmounted and freed cleanly, or one of the following specific error codes:
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal subsystem communication or routing architecture fault occurred.
- MIDIERR_INVALID_CLASS_NUMBER: A security or rule validation exception occurred, typically triggered by an unauthorized attempt to destroy a static hardware-mapped component.
- MIDIERR_INVALID_FLAG: The value passed into the context modifier field ulFlag was not configured to `0`.
- MIDIERR_INVALID_INSTANCE_NUMBER: The instance handle provided in the minstance parameter is invalid, unregistered, or points to an expired memory block.
Remarks
- Automated Link Cascading: When an active instance is destroyed via MIDIDeleteInstance, the MIDI subsystem performs an automated network cleanup sequence. It tears down and unlinks any open routing pipes originating from or terminating at the target instance handle. This prevents the formation of orphaned data references or memory leaks inside the network routing engine.
- Hardware Lifecycle Protections: Logical nodes mapped directly to physical audio equipment interfaces (Hardware Classes/Hardware Nodes) are tied strictly to device driver initialization states. They cannot be targeted or uninstalled via this user-space function call.
- Process Boundary Access Isolation: A calling process can only delete node objects that it explicitly created via MIDICreateInstance. Attempts to terminate instances owned by separate, concurrent application processes will be rejected by the security layer of the subsystem.