mmioInstallIOProc
The mmioInstallIOProc function manages the runtime I/O procedure table for an application. It allows a program to dynamically install a custom I/O procedure, remove one, or locate the entry point of an existing procedure using its Four-Character Code (FOURCC) identifier.
Unlike mmioIniFileHandler, which modifies the permanent initialization file, mmioInstallIOProc affects only the current application's memory and is valid only for the duration of the process.
Syntax
#define INCL_MMIOOS2 #include <os2.h> PMMIOPROC mmioInstallIOProc(FOURCC fccIOProc, PMMIOPROC pIOProc, ULONG ulFlags);
Parameters
- fccIOProc (FOURCC) - input
- The four-character code identifying the I/O procedure (e.g., 'WAVE', 'XYZ ').
- pIOProc (PMMIOPROC) - input
- The address of the I/O procedure's entry point. This must be provided when using the MMIO_INSTALLPROC flag; otherwise, it should be set to `NULL`.
- ulFlags (ULONG) - input
- Specifies the operation. Only one of the following may be used:
- MMIO_INSTALLPROC: Registers the procedure pointed to by `pIOProc`.
- MMIO_REMOVEPROC: Unregisters the procedure associated with `fccIOProc`.
- MMIO_FINDPROC: Searches for the entry point address of the procedure associated with `fccIOProc`.
Return Value
- rc (PMMIOPROC)
- Upon success, returns the **address of the I/O procedure** that was installed, removed, or found.
- Returns `NULL` if the operation fails (e.g., the procedure was not found or installation failed).
Remarks
- Scope: MMIO maintains a private list of I/O procedures for every application. If two different applications register the same FOURCC, they do not conflict with each other.
- Precedence: You can override built-in handlers (like 'DOS' or 'MEM'). The most recently installed procedure for a specific FOURCC is always the one used first.
- Reference Counting: If an application installs the same procedure multiple times, it must call `MMIO_REMOVEPROC` an equal number of times to fully remove it from the table.
- Usage: Once installed, calling mmioOpen with the corresponding FOURCC in the MMIOINFO structure will automatically route all I/O requests to your custom procedure.
Example Code
This example shows how to verify if a handler for 'WAVE' files is currently available in the system.
FOURCC fccWAVE;
PMMIOPROC pIOProc;
fccWAVE = mmioFOURCC('W', 'A', 'V', 'E');
/* Search for the procedure */
pIOProc = mmioInstallIOProc(fccWAVE, NULL, MMIO_FINDPROC);
if (pIOProc == NULL) {
/* WAVE I/O Procedure NOT FOUND */
} else {
/* WAVE I/O Procedure is active at address pIOProc */
}
I/O Procedure Prototype
Any custom I/O procedure must follow this standard entry point signature:
LONG APIENTRY MMIOPROC (PVOID pmmioinfo, USHORT usMsg,
LONG lParam1, LONG lParam2);