mmioGetData
The mmioGetData function allows an application to retrieve the complete MMIOINFO structure associated with an open file handle. This is particularly useful when an application needs to call an I/O procedure directly, as it provides a comprehensive snapshot of the file's current state and configuration.
Syntax
#define INCL_MMIOOS2 #include <os2.h> USHORT mmioGetData(HMMIO hmmio, PMMIOINFO pmmioinfo, USHORT usFlags);
Parameters
- pmmioinfo (PMMIOINFO) - in/out
- A pointer to a caller-allocated MMIOINFO buffer. Upon successful completion, this structure is populated with information about the open file.
- 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 specified file is not opened for buffered I/O.
- MMIOERR_READ_FAILED: A read-advance operation failed.
- MMIOERR_SEEK_FAILED: A seek operation failed.
- MMIOERR_WRITE_FAILED: A write-advance operation failed.
Remarks
While both mmioGetData and mmioGetInfo retrieve information about an open file, there is a key difference:
- mmioGetInfo only fills in fields related to buffered I/O.
- mmioGetData fills in all fields of the MMIOINFO structure.
Because a complete copy of the MMIOINFO structure is required when calling an I/O procedure directly, applications should use mmioGetData for that purpose.
> [!WARNING] > Do not modify any of the fields in the MMIOINFO structure returned by this function, as this information is managed internally by MMIO. To update buffered I/O information, use mmioSetInfo.
Example Code
The following code illustrates how to retrieve the full MMIOINFO data structure for an open file:
HMMIO hmmio1;
MMIOINFO mmioinfo;
USHORT rc;
/* ... file is opened with mmioOpen ... */
/* Initialize the structure */
memset(&mmioinfo, '\0', sizeof(MMIOINFO));
/* Retrieve the full state of the file handle */
rc = mmioGetData(hmmio1, &mmioinfo, 0);
if (rc == MMIO_SUCCESS) {
/* mmioinfo now contains the complete information */
/* Use mmioinfo.pIOProc to call the I/O procedure directly, etc. */
} else {
/* Handle error */
}