mmioCFFindEntry
The mmioCFFindEntry function locates a specific Table of Contents (CTOC) entry in an open RIFF compound file. It can search by element name or traverse the table using various attribute flags.
Syntax
#define INCL_MMIOOS2 #include <os2.h> ULONG mmioCFFindEntry(HMMCF hmmcf, PMMCTOCENTRY pmmctocentry, ULONG ulFlags);
Parameters
- hmmcf (HMMCF) - input
- A RIFF compound-file handle returned by mmioCFOpen.
- pmmctocentry (PMMCTOCENTRY) - in/out
- A pointer to the MMCTOCENTRY structure.
- Input: Contains the name of the element to search for (unless `MMIO_FINDFIRST` is used).
- Output: If successful, the structure is filled with the metadata of the matching entry.
- This structure is variable in size; ensure sufficient memory is allocated for the structure and the appended name.
- ulFlags (ULONG) - input
- Determines the search criteria. `MMIO_FINDFIRST` and `MMIO_FINDNEXT` are mutually exclusive.
- MMIO_FINDFIRST: Locates the first entry in the CTOC.
- MMIO_FINDNEXT: Locates the next entry following the one provided in `pmmctocentry`.
- MMIO_FINDDELETED: Includes or targets entries marked as deleted (`FOURCC_DEL`).
- MMIO_FINDUNUSED: Locates entries marked as unused. (New compound files typically contain 16 unused slots).
Return Values
- rc (ULONG)
- Returns the result of the operation:
- MMIO_CF_SUCCESS: Function succeeded (0).
- MMIOERR_INVALID_HANDLE: The handle passed was not valid.
- MMIOERR_INVALID_PARAMETER: A required parameter (like `pszElementName`) was NULL or invalid.
- MMIOERR_READ_ONLY_FILE: The RIFF compound file is opened as read-only.
- MMIOERR_CF_ENTRY_NOT_FOUND: System failed to find the specified CTOC entry.
- MMIO_CF_FAILURE: The function failed. Call mmioGetLastError for details:
- MMIOERR_WRITE_ONLY_FILE: File not opened in a mode that allows reading.
- MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.
Remarks
Searches performed by name are not case-sensitive. The function behaviors are as follows:
- MMIO_FINDFIRST and MMIO_FINDNEXT cannot be used together.
- If MMIO_FINDFIRST is specified without a name, the first non-deleted entry is returned.
- If MMIO_FINDFIRST and MMIO_FINDDELETED are specified, the first deleted element is returned.
For searches using an element name:
- No flags: Returns the first non-deleted entry matching the name.
- MMIO_FINDNEXT: Finds the entry matching the name, then returns the very next non-deleted entry.
- MMIO_FINDDELETED: Returns the entry matching the name only if it is marked as deleted.
- MMIO_FINDNEXT | MMIO_FINDDELETED: Finds the entry matching the name, then returns the next entry in the table that is deleted.
To iterate through the entire CTOC, start with `MMIO_FINDFIRST` and then perform a series of `MMIO_FINDNEXT` calls using the information returned from each previous call.
Example
HMMCF hmmcf1;
MMCTOCENTRY mmctocentry;
ULONG ulFlags;
ULONG rc;
/* Initialize structure */
memset(&mmctocentry, '\0', sizeof(MMCTOCENTRY));
/* Find the first entry in the compound file */
rc = mmioCFFindEntry(hmmcf1, &mmctocentry, MMIO_FINDFIRST);
if (rc == MMIO_CF_SUCCESS) {
/* Entry found and mmctocentry is populated */
} else {
/* Handle error */
}