mmioIniFileHandler
The mmioIniFileHandler function manages I/O procedure (IOProc) entries within the MMIO initialization file (`MMPMMMIO.INI`). It allows applications to permanently add, remove, find, or replace IOProcs that handle specific file formats or storage systems.
Syntax
#define INCL_MMIOOS2 #include <os2.h> ULONG mmioIniFileHandler(PMMINIFILEINFO pmminifileinfo, ULONG ulFlags);
Parameters
- pmminifileinfo (PMMINIFILEINFO) - input/output
- A pointer to an MMINIFILEINFO structure containing the FOURCC code, DLL name, and procedure name. For search operations, this structure is populated with the matching entry's data.
- ulFlags (ULONG) - input
- Specifies the operation and search criteria.
Operation Flags
- MMIO_INSTALLPROC: Adds an IOProc to the INI file. If a match is found based on search flags, the existing entry is replaced.
- MMIO_REMOVEPROC: Deletes the matching IOProc entry.
- MMIO_FINDPROC: Searches for an entry and fills the MMINIFILEINFO structure.
- MMIO_MATCHFIRST: Finds the first entry matching the criteria.
- MMIO_MATCHNEXT: Finds the next entry following the one provided.
Search/Match Flags
- MMIO_MATCHFOURCC: Matches the `fccIOProc` field (default).
- MMIO_MATCHDLL: Matches the `szDLLName` field.
- MMIO_MATCHPROCEDURENAME: Matches the case-sensitive `szProcName`.
- MMIO_FULLPATH: Includes the drive/path in the DLL name comparison.
- MMIO_EXTENDED_STRUCT: **Required** for OS/2 1.1 and later to indicate the use of the expanded structure.
Return Values
- rc (ULONG)
- Returns MMIO_SUCCESS (0) or an error code:
- MMIOERR_MATCH_NOT_FOUND: No entry matched the criteria.
- MMIOERR_INVALID_DLLNAME: The DLL name is invalid or cannot be validated.
- MMIOERR_INVALID_PROCEDURENAME: The procedure name is invalid.
- MMIOERR_INI_OPEN: Unable to open `MMPMMMIO.INI`.
- MMIOERR_NO_CORE: Memory allocation failed.
Remarks
The `MMPMMMIO.INI` file is located in the directory defined by the MMBASE environment variable.
> [!IMPORTANT] > Changes made by this function are not immediate. The MMIO internal structures are only updated the next time `MMIO.DLL` is loaded (typically upon restarting the application or system).
- Processing Order:**
MMIO treats the INI file entries like a stack (Last-In, First-Out). The **last** entry in the file is the **first** one queried when identifying a file. If you want a specific IOProc to have high priority, ensure it is added last.
In the event of a deletion, the MMIO Manager rewrites the entire file to purge the entry and maintain file integrity, as standard OS/2 INI functions do not reclaim space from deleted items.
Example Code
This snippet demonstrates how to register a custom I/O procedure for a new file format.
MMINIFILEINFO mmIniFileInfo;
ULONG rc;
memset(&mmIniFileInfo, '\0', sizeof(MMINIFILEINFO));
/* Set the unique FOURCC for the format */
mmIniFileInfo.fccIOProc = mmioFOURCC('M', 'Y', 'I', 'O');
/* Specify the DLL and the exported function name */
strncpy(mmIniFileInfo.szDLLName, "MYIOPROC.DLL", 13);
strncpy(mmIniFileInfo.szProcName, "CustomIOEntry", 32);
/* Install the procedure using the extended structure flag */
rc = mmioIniFileHandler(&mmIniFileInfo,
MMIO_INSTALLPROC | MMIO_EXTENDED_STRUCT);
if (rc == MMIO_SUCCESS) {
/* The IOProc will be available after the next MMIO load */
}