MMIOM_SETIMAGE
The MMIOM_SETIMAGE message is sent to an image-specific Multimedia I/O (MMIO) procedure to navigate or select a specific image index inside a multi-frame image container (such as an animated GIF, multi-page TIFF, or icon resource array). It points upcoming read, write, or header configuration routines to the targeted image frame.
Syntax
rc = mmioSendMessage(hmmio, MMIOM_SETIMAGE, imageIndex, lParam2);
Parameters
- pmmioinfo (PMMIOINFO)
- A pointer to an MMIOINFO data structure maintaining the runtime state of the open file channel.
- usMsg (USHORT)
- The message identifier, set to `MMIOM_SETIMAGE`.
- ulParam1 (ULONG)
- The zero-based index of the target image frame to select or instantiate. Its evaluation depends on the current image count:
- Less than the current count: Selects an existing image frame for modification or reading.
- Equal to the current count: Readies the I/O procedure to create and append a brand-new image frame upon the next sequential call to mmioSetHeader.
- Greater than the current count: Deemed invalid and will generate an immediate error.
- lParam2 (LONG)
- This parameter is not used.
Return Value
- rc (ULONG)
- Return codes indicating success or functional constraints:
- MMIO_SUCCESS: The requested image index pointer was shifted or staged successfully.
- MMIO_ERROR: The index exceeded legal ranges, or an internal driver boundary error occurred.
- MMIOERR_UNSUPPORTED_FUNCTION: The current image I/O procedure processes single-frame formats exclusively and does not support multi-image switching.
Remarks
- **Frame Appending Pipeline**: To successfully add a new frame to a multi-image file, the application must follow a precise message sequence. First, send MMIOM_SETIMAGE with `ulParam1` equal to the total current image count (as retrieved via MMIOM_QUERYIMAGECOUNT). Following this handshake, a call to mmioSetHeader (or dispatching MMIOM_SETHEADER) must be executed immediately to define the structural dimensions and allocation size of the new canvas block before committing raw pixel bytes.
- **Driver Failure Interception**: If the underlying image format handler returns `MMIOERR_UNSUPPORTED_FUNCTION`, it indicates a rigid, single-frame codec environment. Applications operating on variable workflows should interpret this fallback to mean that only index `0` is programmatically valid.