mmioDescend

The mmioDescend function descends into a chunk of a RIFF file opened with mmioOpen. It can also search for a given chunk.

Parameters

hmmio

Specifies the file handle of an open RIFF file.

lpck

Specifies a pointer to a caller-supplied MMCKINFO structure that mmioDescend fills with the following information:

The ckid field is the chunk ID of the chunk.

The cksize field is the size of the data portion of the chunk. The data size includes the form type or list type (if any), but does not include the 8-byte chunk header or the pad byte at the end of the data (if any).

The fccType field is the form type if ckid is “RIFF”, or the list type if ckid is “LIST”. Otherwise, it is NULL.

The dwDataOffset field is the file offset of the beginning of the data portion of the chunk. If the chunk is a “RIFF” chunk or a “LIST” chunk, then dwDataOffset is the offset of the form type or list type.

The dwFlags contains other information about the chunk. Currently, this information is not used and is set to zero.

If the MMIO_FINDCHUNK, MMIO_FINDRIFF, or MMIO_FINDLIST flag is specified for uFlags, then the MMCKINFO structure is also used to pass parameters to mmioDescend:

The ckid field specifies the four-character code of the chunk ID, form type, or list type to search for.

lpckParent

Specifies a pointer to an optional caller-supplied MMCKINFO structure identifying the parent of the chunk being searched for. A parent of a chunk is the enclosing chunk—only “RIFF” and “LIST”chunks can be parents. If lpckParent is not NULL, then mmioDescend assumes the MMCKINFO structure it refers to was filled when mmioDescend was called to descend into the parent chunk, and mmioDescend will only search for a chunk within lpckParent to NULL if no parent chunk is being specified.

uFlags

Specifies search options. Contains up to one of the following flags. If no flags are specified,mmioDescend descends into the chunk beginning at the current file position.

Return Value

The return value is zero if the function is successful. Otherwise, the return value specifies an error code. If the end of the file (or the end of the parent chunk, if given) is reached before the desired chunk is found, the return value is MMIOERR_CHUNKNOTFOUND. Other error return values are possible, for instance MMIOERR_CANNOTSEEK.

Comments

A RIFF chunk consists of a four-byte chunk ID (type FOURCC),followed by a four-byte chunk size (type DWORD), followed by the data portion of the chunk, followed by a null pad byte if the size of the data portion is odd. If the chunk ID is “RIFF” or “LIST”, the first four bytes of the data portion of the chunk are a form type or list type (type FOURCC).

If mmioDescend is used to search for a chunk, the file position should be at the beginning of a chunk before calling mmioDescend. The search begins at the current file position and continues to the end of the file. If a parent chunk is specified, the file position should be somewhere within the parent chunk before calling mmioDescend. In this case,the search begins at the current file position and continues to the end of the parent chunk.

If mmioDescend is unsuccessful in searching for a chunk, the current file position is undefined. If mmioDescend is successful, the current file position is changed. If the chunk is a “RIFF” or “LIST” chunk, the new file position will be just after the form type or list type (12 bytes from the beginning of the chunk). For other chunks, the new file position will be the start of the data portion of the chunk (8 bytes from the beginning of the chunk).

For efficient RIFF file I/O, use buffered I/O.

See Also

mmioAscend