MIDIQueryInstanceName
The MIDIQueryInstanceName function retrieves the descriptive, null-terminated symbolic text label assigned to a specific, active MIDI logical node instance.
Syntax
#include <mididll.h> MINSTANCE minstance; /* Instance handle (Input) */ PSZ pszInstanceName; /* Pointer to destination string buffer (Output) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDIQueryInstanceName(minstance, pszInstanceName, ulFlag);
Parameters
- minstance (MINSTANCE) - input
- The specific tracking identification handle of the logical node instance to be queried.
- pszInstanceName (PSZ) - output
- A pointer to a caller-allocated character string buffer. This target destination buffer must be dimensioned to a minimum length of `MIDI_NAME_LENGTH` bytes to safely accommodate the extracted string name and its null-terminator.
- 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 target label string was successfully located and extracted into the buffer, or one of the following diagnostic error codes:
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal subsystem or system communication error occurred.
- MIDIERR_INVALID_FLAG: The value passed into the context tracking parameter ulFlag was not configured to `0`.
- MIDIERR_INVALID_INSTANCE_NUMBER: The instance handle provided in the minstance parameter is invalid, unregistered, or points to an expired memory block.
- MIDIERR_INVALID_PARAMETER: The memory address pointer supplied for pszInstanceName is null, refers to an unmappable memory segment, or points to an unaligned block.
Remarks
- Buffer Size Constraints: Applications must ensure that the string buffer referenced by pszInstanceName is allocated with adequate storage room prior to making the call. Subsystem configurations assume a fixed safety boundary defined by the macro constant `MIDI_NAME_LENGTH`. Passing an under-allocated memory address can result in memory corruption or application instability.
- Instance Handle Validation Hook: Beyond its primary design pattern of extracting string identifiers for user interfaces, MIDIQueryInstanceName can be strategically utilized as a lightweight, non-destructive validation test. If a programmer needs to verify whether an anonymous or cached `MINSTANCE` handle value is still alive and registered inside the active routing matrix without altering the pipeline architecture, executing this function and parsing for a clean zero-return code serves as a diagnostic validation check.