mmioGetInfo
The mmioGetInfo function retrieves information about a file that was opened for buffered I/O. Its primary purpose is to grant an application direct access to the internal I/O buffer, allowing for high-performance reading and writing without the overhead of repeated function calls.
Syntax
#define INCL_MMIOOS2 #include <os2.h> USHORT mmioGetInfo(HMMIO hmmio, PMMIOINFO pmmioinfo, USHORT usFlags);
Parameters
- pmmioinfo (PMMIOINFO) - in/out
- A pointer to a caller-allocated MMIOINFO structure. Upon success, this structure is populated with the current state of the file's buffered I/O system.
- usFlags (USHORT) - input
- Reserved for future use. This value must be set to 0.
Return Values
- rc (USHORT)
- Returns a code indicating the result:
- MMIO_SUCCESS: The function succeeded (0).
- MMIOERR_INVALID_HANDLE: The handle passed was not valid.
- MMIOERR_INVALID_PARAMETER: An invalid parameter was passed.
- MMIOERR_UNBUFFERED: The file was not opened with the `MMIO_BUFFERED` flag.
- MMIOERR_READ_FAILED: A read-advance operation failed.
- MMIOERR_SEEK_FAILED: A seek operation failed.
- MMIOERR_WRITE_FAILED: A write-advance operation failed.
Remarks
Direct Buffer Access
This function is the first step in performing direct I/O. Once you have the MMIOINFO structure:
- Reading: Access data from `pchNext` up to (but not including) `pchEndRead`.
- Writing: Write data to `pchNext` up to (but not including) `pchEndWrite`.
> [!IMPORTANT] > If you modify the buffer, you must set the `MMIO_DIRTY` flag in the `ulFlags` field of the MMIOINFO structure before calling mmioSetInfo or mmioAdvance. If you skip this, your changes will not be written to disk.
Rules for Direct Access
1. **No Mixed Calls:** While you are manually moving the `pchNext` pointer, do not call mmioRead or mmioWrite. 2. **Synchronization:** After you finish manual buffer manipulation, you must call mmioSetInfo to "commit" your pointer changes back to the MMIO system. 3. **Advancing:** If you reach the end of the buffer (`pchNext == pchEndRead` or `pchEndWrite`), call mmioAdvance to fill or flush the buffer and reset the pointers. 4. **Direction:** You must not move `pchNext` backward.
Example Code
The following example shows how to retrieve file information to prepare for direct buffer manipulation:
HMMIO hmmio1;
MMIOINFO mmioinfo;
USHORT rc;
/* Initialize the structure */
memset(&mmioinfo, '\0', sizeof(MMIOINFO));
/* Get current buffer state */
rc = mmioGetInfo(hmmio1, &mmioinfo, 0);
if (rc == MMIO_SUCCESS) {
/* Direct buffer access logic: */
/* Check if we can read at least 10 bytes */
if ((mmioinfo.pchEndRead - mmioinfo.pchNext) >= 10) {
/* Process data at mmioinfo.pchNext directly... */
mmioinfo.pchNext += 10; /* Move the pointer */
/* Update the system with the new pointer position */
mmioSetInfo(hmmio1, &mmioinfo, 0);
}
} else {
/* Handle error (e.g., file not buffered) */
}