MIDIQueryNumInstances
The MIDIQueryNumInstances function retrieves the total count of active logical node instances currently initialized and operating inside the Real-Time MIDI (RTMIDI) link matrix. This scalar value is essential for safe dynamic memory allocation before polling the network graph layout.
Syntax
#include <mididll.h> PULONG pulNumInstances; /* Pointer to total instance counter (Output) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDIQueryNumInstances(pulNumInstances, ulFlag);
Parameters
- pulNumInstances (PULONG) - output
- A pointer to a caller-allocated `ULONG` variable. Upon a successful zero-return, the function populates this variable with the total count of live logical node instances (both hardware interfaces and software stream filters) managed by the subsystem.
- 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 instance ceiling count was successfully extracted, or one of the following diagnostic error codes:
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal subsystem communication or memory infrastructure fault occurred.
- MIDIERR_INVALID_FLAG: The value passed into the context modifier parameter ulFlag was not configured to `0`.
- MIDIERR_INVALID_PARAMETER: The output storage address pointer supplied for pulNumInstances is null or refers to an unmappable memory segment.
Remarks
- Dynamic Sizing Strategy: This API is the structural prerequisite for a clean two-stage network discovery sequence. Because multi-tasking client nodes or physical hardware plug-events fluctuate the size of the logical matrix at runtime, developers must never utilize hardcoded limits. The value updated inside pulNumInstances should immediately be passed to the memory allocator to scale the destination array block for subsequent telemetry extraction: $$\text{Allocation Size} = \text{pulNumInstances} \times \text{sizeof}(\text{MIDIINSTANCEINFO})$$
- Sequence Continuation: Once the memory footprint is allocated, the application completes the extraction process by feeding the calculated scalar count and the uninitialized destination buffer handle directly into MIDIQueryInstanceList.