MIDIQueryClassList
The MIDIQueryClassList function retrieves the structural definition layout, including unique tracking numbers and descriptive names, for all currently registered MIDI node templates and device classes within the active Real-Time MIDI (RTMIDI) subsystem environment.
Syntax
#include <mididll.h> ULONG ulNumClasses; /* Number of classes to query (Input) */ PMIDICLASSINFO paClassInfo; /* Pointer to destination info array (Output) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDIQueryClassList(ulNumClasses, paClassInfo, ulFlag);
Parameters
- ulNumClasses (ULONG) - input
- The specific number of registered classes to profile. This value determines how many matching records the function attempts to write out to the provided destination array buffer.
- paClassInfo (PMIDICLASSINFO) - output
- A pointer to a caller-allocated array of MIDICLASSINFO data structures. Upon successful execution, the subsystem populates each element slice with an internal class identification number paired alongside its formal null-terminated symbolic name.
- 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 class registry snapshot was completely extracted and formatted, or one of the following specific error codes:
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable error occurred within the low-level subsystem router or driver tracking engine.
- MIDIERR_INVALID_CLASS_NUMBER: The value provided in ulNumClasses is evaluated as `0` or explicitly exceeds the total number of live classes currently registered in the system environment.
- MIDIERR_INVALID_FLAG: The value passed into the context tracking parameter ulFlag was not configured to `0`.
- MIDIERR_INVALID_PARAMETER: The memory destination address pointer supplied for paClassInfo is null or refers to an unmappable memory block.
Remarks
- Buffer Dimensioning Strategy: Because the count of registered structural abstractions varies based on active hardware profiles, applications must follow a precise discovery sequence. Before allocating the paClassInfo destination block, the client should dispatch a call to MIDIQueryNumClasses to learn the active size. This retrieved integer must then be used to scale the target memory allocation block size:
$$\text{Allocation Size} = \text{Total Classes} \times \text{sizeof}(\text{MIDICLASSINFO})$$
- Dynamic Driver Registrations: Node structures are inherently fluid. Underlying Type B stream drivers can load, link, register, or cleanly unregister custom software translation classes dynamically at runtime—frequently prompted by independent concurrent client operations. Consequently, client applications should treat cached list reflections as temporary and provide clean mechanisms (such as a user-triggered interface refresh option) to repoll the engine.