MIDICreateInstance
The MIDICreateInstance function allocates and initializes a new runtime node instance belonging to a specified MIDI device or stream filter class. This instantiation registers the logical node within the system's MIDI routing configuration, allowing it to act as a targetable endpoint for linking networks.
Syntax
#include <mididll.h> ULONG ulClassNumber; /* Class number (Input) */ PMINSTANCE pminstance; /* Pointer to the new instance handle (Output) */ PSZ pszInstanceName; /* Unique instance name string (Input) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = MIDICreateInstance(ulClassNumber, pminstance, pszInstanceName, ulFlag);
Parameters
- ulClassNumber (ULONG) - input
- The definitive class identification index representing the functional type of node block to generate (e.g., standard filter nodes or application connection bridges).
- pminstance (PMINSTANCE) - output
- A pointer to an MINSTANCE variable. Upon successful creation, the function populates this storage location with the unique tracking identification handle of the newly spawned node.
- pszInstanceName (PSZ) - input
- A pointer to a null-terminated string containing a unique identifier for the instance. The maximum length of this buffer string is bounded by the `MIDI_NAME_LENGTH` constant.
- ulFlag (ULONG) - input
- A reserved tracking flag parameter. This must be explicitly set to `0`.
Return Value
- rc (ULONG) - returns
- Returns `0` (or `MIDI_SUCCESS`) if the instance is created cleanly, or one of the following specific error codes:
- MIDIERR_DUPLICATE_INSTANCE: The requested string identifier in pszInstanceName is already registered by an active node.
- MIDIERR_INTERNAL_SYSTEM: An unrecoverable internal subsystem or system communication error occurred.
- MIDIERR_INVALID_CLASS_NUMBER: The specified value in ulClassNumber does not map to a recognized or registered class template type.
- MIDIERR_INVALID_FLAG: The value passed into ulFlag was not set to `0`.
- MIDIERR_INVALID_INSTANCE_NAME: The string layout or length constraints pointed to by pszInstanceName are invalid.
- MIDIERR_INVALID_PARAMETER: The output address buffer pointer for pminstance is null or points to protected memory regions.
- MIDIERR_NOT_ALLOWED: The client context attempted an unauthorized allocation pattern, such as trying to instantiate a duplicate second application node.
- MIDIERR_RESOURCE_NOT_AVAILABLE: The subsystem cannot allocate memory pools, tracking blocks, or handle slots required to provision the new object instance.
Remarks
- Hardware Constraint Boundary: Physical component nodes (Hardware Classes/Hardware Nodes) are mapped exclusively during hardware driver detection cycles. Applications cannot manually construct hardware instances via this call.
- Process Ownership Rules: The calling process that dispatches MIDICreateInstance is permanently designated as the logical owner of the resulting node. This design pattern shapes operational scopes across the system network: a process is strictly barred from modifying, connecting, or destroying MIDI nodes owned by external, independent processes.
- Network Topology Building: Once an instance handle is retrieved through this routine, it can be combined with other endpoints to construct media pipes using connection links.