mmioAscend
This function ascends out of a chunk in a RIFF file that was descended into by mmioDescend or created by mmioCreateChunk.
Syntax
#define INCL_MMIOOS2 #include <os2.h> HMMIO hmmio; /* Open file handle. */ PMMCKINFO pckinfo; /* Pointer to MMCKINFO. */ USHORT usFlags; /* Reserved. */ USHORT rc; /* Return codes. */ rc = mmioAscend(hmmio, pckinfo, usFlags);
Parameters
- pckinfo (PMMCKINFO) - input
- A pointer to the MMCKINFO structure that was filled by mmioDescend or mmioCreateChunk.
- usFlags (USHORT) - input
- Reserved for future use and must be set to zero.
Return Value
- rc (USHORT) - returns
- Return codes indicating success or type of failure:
- MMIO_SUCCESS: If the function succeeds, 0 is returned.
- MMIOERR_INVALID_HANDLE: The handle passed was not valid.
- MMIOERR_INVALID_PARAMETER: The parameter passed was not correct.
- MMIOERR_CANNOTWRITE: The I/O buffer needs to be written to disk but disk space is lacking.
Remarks
If the chunk was descended into using mmioDescend, then `mmioAscend` seeks to the location following the end of the chunk (past the extra pad byte, if any).
If the chunk was created and descended into using mmioCreateChunk, or if the `MMIO_DIRTY` flag in the `ulFlags` field of the MMCKINFO structure is set, then the current file position is assumed to mark the end of the data portion of the chunk.
If the actual chunk size differs from the value stored in the `ckSize` field of MMCKINFO before the original descend or create call, `mmioAscend` seeks back and corrects the chunk size in the chunk header before ascending. Additionally, if the chunk size is odd, `mmioAscend` writes a NULL pad byte at the end of the chunk to maintain RIFF alignment.
Example Code
The following code illustrates how to move the file position by ascending from a chunk.
HMMIO hmmio1;
MMCKINFO mmckinfo;
USHORT usFlags = 0;
USHORT rc;
...
memset( &mmckinfo, '\0', sizeof(MMCKINFO) );
/* Assume mmckinfo was filled by a previous mmioDescend call */
rc = mmioAscend(hmmio1, &mmckinfo, usFlags);
if (rc) {
/* error */
} else {
/* Position is now past the end of the chunk */
}