mmioFindElement
The mmioFindElement function provides a high-level interface for enumerating or searching for specific elements within a RIFF compound file (such as a bundle file). It supports iterative searching and is available as both a 16-bit and 32-bit entry point.
Syntax
#define INCL_MACHDR #include <os2.h> ULONG mmioFindElement(ULONG ulCode, PSZ pszElement, ULONG ulElementLen, PSZ pszFile, ULONG ulReserved);
Parameters
- ulCode (ULONG) - input
- Specifies the operation to perform:
- MMIO_FE_FINDFIRST: Locates the first element in the compound file. Opens the file for enumeration.
- MMIO_FE_FINDNEXT: Locates the next element in the sequence.
- MMIO_FE_FINDELEMENT: Searches for a specific element name provided in pszElement. This supersedes any active FindFirst/Next search.
- MMIO_FE_FINDEND: Terminates the search and closes the compound file. This must be called to avoid resource leaks.
- pszElement (PSZ) - in/out
- A pointer to a buffer.
- For `FINDFIRST` and `FINDNEXT`, this buffer is populated with the name of the found element.
- For `FINDELEMENT`, the caller provides the name to search for in this buffer.
- ulElementLen (ULONG) - input
- The size, in bytes, of the pszElement buffer.
- pszFile (PSZ) - input
- A pointer to a string containing the name of the compound file (e.g., "DOCS.BND"). Do not include element names in this path.
- ulReserved (ULONG) - input
- Reserved for future use. This value must be set to 0.
Return Values
- rc (ULONG)
- Returns 0 (`MMIO_SUCCESS`) if successful, or one of the following errors:
- MMIOERR_CF_ENTRY_NOT_FOUND: The element was not found or the end of the list was reached.
- MMIOERR_INVALID_PARAMETER: A required parameter is missing.
- ERROR_INVALID_PARAMETER: ulReserved was not zero.
- ERROR_BUFFER_OVERFLOW: The element name is longer than ulElementLen.
Remarks
The function manages the state of the compound file internally. When you call `MMIO_FE_FINDFIRST`, the file is opened and remains open to facilitate fast sequential access during `MMIO_FE_FINDNEXT` calls. Because only one enumeration sequence is supported per file at a time, starting a new search will reset the previous context.
> [!IMPORTANT] > Always call mmioFindElement with `MMIO_FE_FINDEND` when your search is complete. This ensures that the system releases the file handle associated with the compound file.
Example Code
The following code illustrates how to loop through every element in a bundle file named "TEST.BND":
ULONG rc;
CHAR szElement[CCHMAXPATH];
/* 1. Start the search */
rc = mmioFindElement(MMIO_FE_FINDFIRST, szElement, CCHMAXPATH, "TEST.BND", 0);
while (rc == MMIO_SUCCESS) {
/* Process the found element name in szElement */
/* (e.g., save name, open element, etc.) */
/* 2. Find the next entry */
rc = mmioFindElement(MMIO_FE_FINDNEXT, szElement, CCHMAXPATH, "TEST.BND", 0);
}
/* 3. Always end the search to close the file */
mmioFindElement(MMIO_FE_FINDEND, szElement, CCHMAXPATH, "TEST.BND", 0);