MMIOM_QUERYIMAGE
The MMIOM_QUERYIMAGE message is sent to an image-specific Multimedia I/O (MMIO) procedure to determine the index of the currently active or selected image within a multi-image file container (such as an animated GIF, an icon bundle, or a multi-page TIFF).
Syntax
rc = mmioSendMessage(hmmio, MMIOM_QUERYIMAGE, (LONG)pulImageIndex, 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_QUERYIMAGE`.
- pulParam1 (PULONG)
- A pointer to a `ULONG` variable where the I/O procedure writes the current image index. Image indexes are zero-based (e.g., `0` refers to the first image frame in the file).
- lParam2 (LONG)
- This parameter is not used.
Return Value
- rc (ULONG)
- Return codes indicating success or functional fallback states:
- MMIO_SUCCESS: The request was successful, and the value pointed to by pulParam1 has been updated.
- MMIO_ERROR: An error occurred while communicating with the driver or parsing the container structure.
- MMIOERR_UNSUPPORTED_FUNCTION: The message is not supported by the current image I/O procedure. This indicates that the file format does not support multiple frames, and the application should assume by default that the 0th index image is selected.
Remarks
- **Multi-Frame Tracking**: For image formats capable of packaging multiple distinct frames or layers into a single disk file, this message provides the necessary feedback loop to verify exactly which layer is targeted for upcoming read or write operations.
- **Safe Fallback**: If an I/O procedure returns `MMIOERR_UNSUPPORTED_FUNCTION`, it is a safe signal that the media handler treats all files as single-frame flat canvases. Applications should handle this code by manually zeroing out their tracking index variable instead of throwing a hard error.