MIDITimer
The MIDITimer function controls the operational state of the global Real-Time MIDI (RTMIDI) master subsystem clock. It toggles the scheduling engine timer loop on or off, allowing timed scheduling pipelines to activate or freeze.
Syntax
#include <mididll.h> ULONG ulAction; /* Timer state action modifier (Input) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDITimer(ulAction, ulFlag);
Parameters
- ulAction (ULONG) - input
- Specifies the state modification directive for the subsystem master clock. This parameter must be set to one of the following mutually exclusive constants:
- MIDI_START_TIMER: Commences or resumes the high-priority multimedia time stream tracking loop.
- MIDI_STOP_TIMER: Freezes the active master clock progression and halts deferred event scheduling execution.
- 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 clock state transition completed successfully, or one of the following diagnostic error codes:
- MIDIERR_HARDWARE_FAILED: A critical, low-level platform architecture or audio-hardware-backed clock generator failure occurred while altering states.
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal processing error or thread management exception occurred inside the active scheduling router.
- MIDIERR_INVALID_FLAG: The value passed into the context tracking modifier parameter ulFlag was not configured to `0`.
- MIDIERR_INVALID_PARAMETER: The value passed into ulAction does not map to a recognized clock directive constant.
Remarks
- Operational Exclusivity: The execution directives `MIDI_START_TIMER` and `MIDI_STOP_TIMER` are completely mutually exclusive operations. Calling an active timer with a secondary start directive or a stopped timer with a stop directive results in safe, idempotent tracking state preservation unless internal communication links fail.
- Pipeline Sequencing Prerequisite: Starting the subsystem timer is a critical, mandatory prerequisite before any application can successfully route background-scheduled time vectors using MIDISendMessages. If the master clock loop remains uninitiated or has been frozen via `MIDI_STOP_TIMER`, down-stream attempts to queue absolute future event structures will fail, returning a `MIDIERR_INTERNAL_SYSTEM` code.