MMIOM_GETHEADER
The MMIOM_GETHEADER message is sent to a Multimedia I/O (MMIO) procedure to request media-specific metadata and header information for the currently open file or container sub-element.
Syntax
bytesCopied = mmioSendMessage(hmmio, MMIOM_GETHEADER, (LONG)pHeaderStructure, lParam2);
Parameters
- pmmioinfo (PMMIOINFO)
- A pointer to an MMIOINFO data structure maintaining the current state of the open file.
- usMsg (USHORT)
- The message identifier, set to `MMIOM_GETHEADER`.
- lParam1 (LONG)
- A pointer to a caller-allocated, format-specific header buffer block where the I/O procedure will write the metadata payload.
- lParam2 (LONG)
- The length, in bytes, of the target structure buffer provided in lParam1.
Return Value
- rc (ULONG)
- Returns structural transaction metrics or error states:
- Greater than 0: Successful completion; returns the exact number of bytes copied into the target structure.
- 0: A general failure occurred, and no metadata was written.
- If an error occurs, the I/O procedure sets the `ulErrorRet` field of the MMIOINFO structure to one of the following codes:
- MMIOERR_INVALID_BUFFER_LENGTH: The buffer size specified in lParam2 is too small to safely hold the format header.
- MMIOERR_INVALID_STRUCTURE: The existing header structure inside the file is corrupt or invalid.
Remarks
- **Target Structures**: Depending on the underlying media flavor parsed by the active `FOURCC` codec, lParam1 can target a variety of platform structures:
- MMIMAGEHEADER: Image dimensions, compression level, bit depth, and an integrated color palette.
- MMAUDIOHEADER: Audio sampling rate, channels, bit depth, and duration metrics.
- MMMIDIHEADER: Native MIDI sequence constraints and track layouts.
- MMMOVIEHEADER / MMVIDEOHEADER: Digital video frame interleaving, frame rates, and structural canvas metrics.
- **Header Translation**: When standard format conversion flags are active, the I/O procedure is responsible for translating native, non-standard, or packed hardware container header formats into standard, OS/2-compliant presentation structures.
- **Prerequisites**: Unlike global configuration queries, this message requires a fully initialized and active file context contextually generated by a successful MMIOM_OPEN transaction.