MMIOM_BEGINRECORD
The MMIOM_BEGINRECORD message is sent to a Multimedia I/O (MMIO) procedure to indicate the start of a logical grouping of write operations. When an I/O procedure receives this message, it bundles all subsequent `mmioWrite` calls into a single transaction or logical unit until a corresponding MMIOM_ENDRECORD message is received. This allows the combined changes to be reversed or reapplied in one step using undo and redo operations.
Syntax
rc = mmioSendMessage(hmmio, MMIOM_BEGINRECORD, lParam1, 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_BEGINRECORD`.
- lParam1 (LONG)
- This parameter is not used.
- lParam2 (LONG)
- This parameter is not used.
Return Value
- rc (ULONG)
- Return codes indicating success or failure:
- MMIO_SUCCESS: The I/O procedure successfully opened a new undo/redo logical record.
- MMIO_ERROR: An error occurred, and a logical record was not started.
Remarks
This message is a crucial component for applications that implement complex editing features like non-destructive audio or video cutting, pasting, and mixing.
- Transactional Bundling: Instead of treating every individual buffer write as a standalone state change, MMIOM_BEGINRECORD prompts the I/O procedure to checkpoint the file state.
- Undo/Redo Interaction: Once bounded by a matching MMIOM_ENDRECORD, this block of modifications becomes a single element on the I/O history stack. When the application issues an MMIOM_UNDO or MMIOM_REDO message, the I/O procedure rolls back or replays the entire sequence of writes as one discrete operation.
- Custom I/O Procedures: Custom storage handlers and compound file format parsers must track whether a recording transaction is active to manage their internal translation tables or transaction history buffers correctly.