MIDISetup
The MIDISetup function establishes a generic operational environment context for an application connecting to the Real-Time MIDI (RTMIDI) subsystem. It negotiates structural configuration values, sets constraints for long-form System Exclusive (SysEx) streaming operations, and returns a high-priority pointer to the master subsystem clock.
Syntax
#include <mididll.h> PMIDISETUP pMidiSetup; /* Pointer to setup configuration block (Input/Output) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDISetup(pMidiSetup, ulFlag);
Parameters
- pMidiSetup (PMIDISETUP) - input/output
- A pointer to a caller-allocated MIDISETUP structure. On input, this structure passes desired configuration boundaries to the subsystem. On successful zero-return, the subsystem modifies fields within this block to return active configuration data and memory addresses.
- 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 environmental negotiation completed successfully, or one of the following specific error codes:
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable initialization error occurred within the low-level device driver layer.
- MIDIERR_INVALID_FLAG: The value passed into the context tracking modifier parameter ulFlag was not configured to `0`.
- MIDIERR_INVALID_PARAMETER: The memory address pointer supplied for pMidiSetup is null or refers to an unmapped storage block.
- MIDIERR_INVALID_SETUP: The structural configuration fields within the supplied MIDISETUP layout contain illegal or unsupported values.
Remarks
- Subsystem Core Negotiation: In the current architecture, MIDISetup acts as a dual-purpose handshake. It determines the maximum acceptable message length constraints for streaming real-time SysEx data blocks and registers a direct memory access link to the absolute subsystem clock.
- Timer Resolution Distinction: It is critical that software developers do not confuse the tracking pointer exposed in the MIDISETUP layout with the generic system timer address obtained via `TimerGetPointer`.
- `TimerGetPointer` references the independent High-Resolution Timer (HRT) architecture.
- MIDISetup provides a dedicated pointer directly tracking the internal **RTMIDI master clock**.
- **Timestamp Scheduling Rationale**: The RTMIDI-specific timer pointer returned by this call must be used as the absolute baseline value for filling out the scheduling field (`ulTime` within the MESSAGE structure) when dispatching timed event lists through MIDISendMessages. Because this master subsystem clock is architected to dynamically slave and synchronize to external timing anchors—such as linear SMPTE timecode lines or OS/2 Multimedia Presentation Manager stream positions—relying on the standard HRT instead will result in sequencing drift and broken synchronization.