MIDIRemoveLink
The MIDIRemoveLink function severs an existing data connection between a specific output slot of a source node instance (`minstanceSource`) and a target destination node instance (`minstanceTarget`) within the active Real-Time MIDI (RTMIDI) link matrix.
Syntax
#include <mididll.h> MINSTANCE minstanceSource; /* Source instance handle (Input) */ MINSTANCE minstanceTarget; /* Target instance handle (Input) */ ULONG ulSlotNumber; /* Source output slot number (Input) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDIRemoveLink(minstanceSource, minstanceTarget, ulSlotNumber, ulFlag);
Parameters
- minstanceSource (MINSTANCE) - input
- The logical tracking identification handle of the source node instance from which the connection originates.
- minstanceTarget (MINSTANCE) - input
- The logical tracking identification handle of the target destination node instance where the data stream terminates.
- ulSlotNumber (ULONG) - input
- The specific pin or output slot index on the source instance associated with the connection targeted for removal.
- ulFlag (ULONG) - input
- A reserved subsystem tracking modifier flag. This must be explicitly set to `0`.
Return Value
- rc (ULONG) - returns
- Returns `0` (or `MIDI_SUCCESS`) if the specified network connection was successfully severed and deleted, or one of the following diagnostic error codes:
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal subsystem error occurred within the routing matrix manager.
- MIDIERR_INVALID_FLAG: The value passed into the context tracking modifier parameter ulFlag was not configured to `0`.
- MIDIERR_INVALID_INSTANCE_NUMBER: Either the minstanceSource or minstanceTarget logical handle values provided are invalid, unregistered, or point to an expired instance context.
- MIDIERR_INVALID_PARAMETER: The specified ulSlotNumber refers to a non-existent or out-of-bounds output slot index on the source node.
- MIDIERR_NOT_ALLOWED: The calling process context does not own the target link. A process can only destroy data links that it originally instantiated.
Remarks
- **Strict Ownership Constraints**: The RTMIDI connection topology enforces a strict security boundaries model across concurrent client operations. A process cannot maliciously or accidentally modify the routing structure of another program. Consequently, any attempt to sever a link via MIDIRemoveLink will fail with a `MIDIERR_NOT_ALLOWED` response code if the link was originally generated by an independent background application thread or external process ID.
- **Pipeline Synchronization**: Severing a connection instantly halts the data transmission pipeline between the selected source slot and target components. Software filter instances or output nodes must clean up any pending stream states or active voice parameters (such as sending an all-notes-off message sequence if necessary) before deleting links to prevent hanging synthesizer tones downstream.