mmioIdentifyFile
The mmioIdentifyFile function determines the format of a file and identifies the appropriate I/O procedure (IOProc) required to process it. It accomplishes this by examining the file name extension or, more reliably, by querying installed I/O procedures to inspect the file's internal signature (magic numbers).
Syntax
#define INCL_MMIOOS2 #include <os2.h> ULONG mmioIdentifyFile(PSZ pszFileName, PMMIOINFO pmmioinfo, PMMFORMATINFO pmmformatinfo, PFOURCC pfccStorageSystem, ULONG ulReserved, ULONG ulFlags);
Parameters
- pszFileName (PSZ) - input
- A pointer to a null-terminated string containing the name of the file to identify.
- pmmioinfo (PMMIOINFO) - input
- A pointer to an MMIOINFO structure. This is typically set to NULL. It is used primarily when dealing with RIFF compound-file elements that may not be completely valid.
- pmmformatinfo (PMMFORMATINFO) - in/out
- A pointer to an MMFORMATINFO structure. On successful return, this structure is filled with details about the format, including the media type (audio, image, etc.) and the fccIOProc (the FOURCC code of the IOProc that can handle the file).
- pfccStorageSystem (PFOURCC) - output
- A pointer to a FOURCC variable that receives the FOURCC code of the storage system (e.g., DOS, BND) used by the file.
- ulReserved (ULONG) - input
- Reserved for future use. Must be set to 0.
- ulFlags (ULONG) - input
- Flags that control how the identification process is performed:
- MMIO_FORCE_IDENTIFY_SS: Forces the system to identify the storage system by querying IOProcs rather than relying on the file name.
- MMIO_FORCE_IDENTIFY_FF: Forces the system to identify the file format by querying IOProcs rather than relying on the file name.
Return Values
- rc (ULONG)
- Returns a code indicating the result:
- MMIO_SUCCESS: The file was successfully identified (0).
- MMIO_ERROR: The function failed to identify the file.
- MMIOERR_INVALID_PARAMETER: An invalid parameter was passed.
- MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.
> [!TIP] > If a DOS file error occurs during the process, use mmioGetLastError to retrieve the specific system error code.
Remarks
The MMIO Manager maintains a list of installed I/O procedures. When mmioIdentifyFile is called, it searches this list to find a match.
- The search order is determined by the `MMPMMMIO.INI` file and the order of installation via mmioInstallIOProc.
- Generally, the most recently installed IOProc is checked first.
- If no specific media IOProc claims the file, the default match is the standard **DOS** I/O procedure.
Identifying a file via its contents (using the `FORCE` flags) is significantly more robust than identifying via file extension, as it prevents errors caused by incorrectly named files.
Example Code
This example identifies a file to determine which IOProc should be used to open it.
MMIOINFO mmioinfo;
MMFORMATINFO mmFormatInfo;
FOURCC fccStorageSystem;
ULONG rc;
memset(&mmioinfo, '\0', sizeof(MMIOINFO));
memset(&mmFormatInfo, '\0', sizeof(MMFORMATINFO));
rc = mmioIdentifyFile("sample.wav",
&mmioinfo,
&mmFormatInfo,
&fccStorageSystem,
0,
MMIO_FORCE_IDENTIFY_FF);
if (rc == MMIO_SUCCESS) {
/* mmFormatInfo.fccIOProc now contains the ID needed for mmioOpen */
/* mmFormatInfo.ulMediaType might be MMIO_MEDIATYPE_AUDIO */
}