mmioDescend
The mmioDescend function descends into a RIFF chunk beginning at the current file position or searches for a specified chunk within a RIFF file.
Syntax
#define INCL_MMIOOS2 #include <os2.h> USHORT mmioDescend(HMMIO hmmio, PMMCKINFO pckinfo, PMMCKINFO pckinfoParent, USHORT usFlags);
Parameters
- pckinfo (PMMCKINFO) - input/output
- A pointer to a caller-supplied MMCKINFO structure that the function populates with the following:
- ckid: The chunk ID of the found/descended chunk.
- ckSize: The size of the data portion (excluding the 8-byte header and any pad byte).
- fccType: The form type (for RIFF) or list type (for LIST).
- ulDataOffset: The file offset of the beginning of the data portion.
- ulFlags: Currently initialized to zero by the function.
- pckinfoParent (PMMCKINFO) - input
- An optional pointer to an MMCKINFO structure representing the parent chunk (only RIFF or LIST chunks can be parents). If provided, the search is restricted to the data area of this parent chunk.
- usFlags (USHORT) - input
- Determines the search/descent behavior:
- 0: Descends into the chunk starting at the current file position.
- MMIO_FINDCHUNK: Searches for a chunk with the specific ID provided in the `ckid` field of pckinfo.
- MMIO_FINDRIFF: Searches for a RIFF chunk with the specific form type provided in the `fccType` field of pckinfo.
- MMIO_FINDLIST: Searches for a LIST chunk with the specific list type provided in the `fccType` field of pckinfo.
Return Values
- rc (USHORT)
- Returns a code indicating the result:
- MMIO_SUCCESS: The function succeeded (0).
- MMIOERR_INVALID_HANDLE: The handle passed was not valid.
- MMIOERR_INVALID_PARAMETER: A parameter was not correct.
- MMIOERR_CHUNKNOTFOUND: The end of the file (or parent chunk) was reached before the desired chunk was found.
Remarks
A RIFF chunk consists of a 4-byte ID, a 4-byte size, and the data portion (optionally followed by a pad byte if the size is odd). RIFF and LIST chunks include an additional 4-byte type field at the start of their data area.
When mmioDescend succeeds:
- For **standard chunks**, the file position is set 8 bytes from the start of the chunk (immediately after the header).
- For **RIFF or LIST chunks**, the file position is set 12 bytes from the start (immediately after the form/list type).
For optimal performance, use buffered I/O by setting up the hmmio handle accordingly.
Example Code
The following example demonstrates how to find and descend into a RIFF 'WAVE' chunk:
HMMIO hmmio1;
MMCKINFO mmckinfo;
USHORT rc;
/* Initialize structure and set the form type we are looking for */
memset(&mmckinfo, '\0', sizeof(MMCKINFO));
mmckinfo.fccType = mmioFOURCC('W', 'A', 'V', 'E');
/* Search for the RIFF WAVE chunk from the current position */
rc = mmioDescend(hmmio1, &mmckinfo, NULL, MMIO_FINDRIFF);
if (rc != MMIO_SUCCESS) {
/* Error: Chunk not found or invalid file */
} else {
/* Successfully descended into the WAVE chunk.
File pointer is now positioned at the first sub-chunk. */
}