MIDIQueryInstanceList
The MIDIQueryInstanceList function retrieves a sequential snapshot containing detailed configuration, relationship, and descriptive telemetry records for all live logical node instances populated inside the active Real-Time MIDI (RTMIDI) network.
Syntax
#include <mididll.h> ULONG ulNumInstances; /* Number of instances to query (Input) */ PMIDIINSTANCEINFO paInstanceInfo; /* Pointer to destination info array (Output) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDIQueryInstanceList(ulNumInstances, paInstanceInfo, ulFlag);
Parameters
- ulNumInstances (ULONG) - input
- The specific number of active instances to profile. This parameter acts as a hard boundary for the count of tracking elements the subsystem will attempt to parse into the destination array.
- paInstanceInfo (PMIDIINSTANCEINFO) - output
- A pointer to a caller-allocated array of MIDIINSTANCEINFO data structures. Upon a successful zero-return, the subsystem populates each element slice with comprehensive tracking data, including the internal instance handle, parent class assignment index, string-mapped symbolic name, total attached network link counters, and intrinsic capability attributes.
- 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 network node list reflection was completely extracted and formatted, or one of the following diagnostic error codes:
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal error occurred within the core tracking engine or routing supervisor.
- MIDIERR_INVALID_FLAG: The value passed into the context modifier parameter ulFlag was not configured to `0`.
- MIDIERR_INVALID_PARAMETER: The memory address pointer supplied for paInstanceInfo is null, points to protected memory space, or the value specified in ulNumInstances evaluates to an invalid boundary condition.
Remarks
- Buffer Sizing Protocol: Because the volume of operational instances within the network fluctuates based on application states and hardware attachment cycles, the client layout must follow a dynamic discovery paradigm. Applications must issue a call to MIDIQueryNumInstances first to poll the running instance ceiling, using that returned count to size the targeted destination block allocation:
$$\text{Allocation Size} = \text{Total Instances} \times \text{sizeof}(\text{MIDIINSTANCEINFO})$$
- Hardware Instance Definitions: The symbolic text labels and string names returned inside the info structures for physical interface blocks (Hardware Nodes) are assigned statically by the lower-level device drivers during initialization based on hardware discovery strings.
- Dynamic Lifecycle Refresh Patterns: The environment layout is highly transactional; background multimedia tasks or concurrent client programs can register software filter blocks or discard connections at any time. Applications should avoid caching this list long-term and are highly encouraged to map user-driven UI refresh triggers or automatic validation check loops.
- Target Optimization Practice: While this function captures every structural block in the engine layout, standard user applications typically query this list exclusively to extract the sub-array of hardware interfaces to expose available MIDI input and output ports to the end user. It is best practice to run this routine each time a device configuration interface window is opened or updated.