MIDIQueryNumClasses
The MIDIQueryNumClasses function retrieves the total count of distinct MIDI device and logical stream filter classes currently registered inside the active Real-Time MIDI (RTMIDI) subsystem. This count acts as the baseline scalar needed to allocate destination memory blocks for registry discovery.
Syntax
#include <mididll.h> PULONG pulNumClasses; /* Pointer to total class counter (Output) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDIQueryNumClasses(pulNumClasses, ulFlag);
Parameters
- pulNumClasses (PULONG) - output
- A pointer to a caller-allocated `ULONG` variable. Upon successful zero-return, the function updates this variable with the total number of registered component classes currently tracked by the system router.
- 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 active class count was successfully queried and updated, or one of the following specific error codes:
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal subsystem communication or driver infrastructure fault occurred.
- MIDIERR_INVALID_FLAG: The value passed into the context tracking modifier ulFlag was not configured to `0`.
- MIDIERR_INVALID_PARAMETER: The output address buffer pointer for pulNumClasses is null or references an unmappable memory region.
Remarks
- Registry Memory Dimensioning: This function serves as the initial step in a precise two-stage registry discovery pattern. Because the internal class registry table is highly dynamic, software layers must first determine the size of the table before pulling its contents. The application utilizes the integer returned in pulNumClasses to securely calculate and allocate a memory block dimensioned to fit the precise array footprint requirements of the subsystem:
$$\text{Allocation Size} = \text{pulNumClasses} \times \text{sizeof}(\text{MIDICLASSINFO})$$
- Sequence Continuation: Immediately following the allocation of the array buffer, the application handles the secondary phase by passing the matching scalar counter value and the newly generated buffer block destination into MIDIQueryClassList.