MMIOM_READ
The MMIOM_READ message is sent to a Multimedia I/O (MMIO) procedure by the mmioRead function to request that a specified number of bytes be read from an open file or element into a caller-supplied buffer.
Syntax
bytesRead = mmioSendMessage(hmmio, MMIOM_READ, (LONG)pszBuffer, bytesToRead);
Parameters
- pmmioinfo (PMMIOINFO)
- A pointer to an MMIOINFO data structure maintaining the current state of the open file channel. The I/O procedure updates the state tracking fields, such as `lDiskOffset`, during the read operation.
- usMsg (USHORT)
- The message identifier, set to `MMIOM_READ`.
- lParam1 (LONG)
- A pointer to the destination data buffer (`PSZ`) where the read bytes will be stored.
- lParam2 (LONG)
- The total number of bytes requested to be read from the file.
Return Value
- rc (ULONG)
- Returns transaction metrics or error states:
- Greater than 0: The actual number of bytes successfully read from the file and copied into the buffer.
- 0L: End of file (EOF) encountered; no more bytes can be read from the current position.
- MMIO_ERROR: The read operation failed due to a device, file system, or network error.
Remarks
- **Data Translation**: If translation flags (such as `MMIO_TRANSLATEDATA`) were specified when the file was opened, the I/O procedure is responsible for converting the raw data stored on disk into the standard presentation format before copying it to the buffer. For example, it might decompress an audio stream or convert a proprietary image chunk layout into a standard bitmap frame.
- **Seek Pointer Maintenance**: Upon successfully pulling bytes out of the stream, the I/O procedure must advance the internal file position tracking marker (`lDiskOffset` inside the MMIOINFO structure) by the exact amount returned in rc to ensure subsequent sequential operations execute from the correct offset.