MIDIQueryVersion
The MIDIQueryVersion function retrieves the operational software version metrics for both the user-space Real-Time MIDI (RTMIDI) dynamic link library (`MIDIDLL.DLL`) and its paired low-level subsystem device driver.
Syntax
#include <mididll.h> PULONG pulVersion; /* Pointer to composite version bitmask (Output) */ ULONG rc; /* Return code */ rc = MIDIQueryVersion(pulVersion);
Parameters
- pulVersion (PULONG) - output
- A pointer to a caller-allocated `ULONG` variable. Upon a successful zero-return, this variable receives a composite 32-bit integer containing packed bitfields that define the subsystem lifecycle stages.
Return Value
- rc (ULONG) - returns
- Returns `0` (or `MIDI_SUCCESS`) if the version data was cleanly extracted, or one of the following diagnostic error codes:
- MIDIERR_INVALID_PARAMETER: The output address buffer pointer supplied for pulVersion is null or refers to an unmappable memory segment.
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal subsystem or system communication error occurred.
- MIDIERR_NO_DRIVER: The core RTMIDI device driver is missing, not loaded, or failed to initialize during the system boot sequence.
Remarks
- Subsystem Diagnostic Verification: This routine is designed as a foundational environment handshake. Applications should invoke MIDIQueryVersion as their very first programmatic interaction with the MIDI library to safely verify that the core kernel-space infrastructure is responsive and running before calling downstream node allocation routines.
- Packed Data Layout Interpretation: The returned 32-bit value packs two independent 16-bit version blocks. The **upper 16 bits** represent the user-space API DLL version, while the **lower 16 bits** represent the active kernel-space hardware driver version. Each 16-bit block is parsed using the following bitfield offsets:
| Bits | Width | Field Name | Description |
|---|---|---|---|
| `14–15` | 2 bits | **Major** | Major release generation number. |
| `10–13` | 4 bits | **Minor** | Minor capability revision step. |
| `6–9` | 4 bits | **Bug Fix #** | Maintenance tracking / patch counter. |
| `4–5` | 2 bits | **Phase** | Software release stability cycle phase. |
| `0–3` | 4 bits | **Build #** | Compilation sequence number. |
- **Phase Bit Definitions**: The 2-bit Phase field decodes into the following release classifications:
- `00` — **Development**: Internal pre-release engineering builds.
- `01` — **Beta**: Early testing release.
- `10` — **Alpha**: Preliminary feature-complete layout.
- `11` — **GA** (General Availability): Stable production software release.
Macro Helper Example
To cleanly unpack the composite payload returned in pulVersion, the following C preprocessing layout can be used:
#define GET_DLL_VERSION(v) ((v) >> 16) #define GET_DRV_VERSION(v) ((v) & 0xFFFF) #define UNPACK_MAJOR(v16) (((v16) >> 14) & 0x03) #define UNPACK_MINOR(v16) (((v16) >> 10) & 0x0F) #define UNPACK_BUGFIX(v16) (((v16) >> 6) & 0x0F) #define UNPACK_PHASE(v16) (((v16) >> 4) & 0x03) #define UNPACK_BUILD(v16) ((v16) & 0x0F)