mmioCreateChunk
The mmioCreateChunk function creates a new chunk in a RIFF file at the current file position. It writes the chunk header and "descends" into the chunk, preparing the file for data writing.
Syntax
#define INCL_MMIOOS2 #include <os2.h> USHORT mmioCreateChunk(HMMIO hmmio, PMMCKINFO pckinfo, USHORT usFlags);
Parameters
- pckinfo (PMMCKINFO) - input
- A pointer to an MMCKINFO structure. The caller must initialize specific fields, and the function populates others upon return:
- ckid: The FOURCC identifier for the chunk. If `MMIO_CREATERIFF` or `MMIO_CREATELIST` is specified, this field is filled by the function.
- ckSize: The size of the data portion of the chunk (excluding the 8-byte header). If the actual amount of data written differs when mmioAscend is called, the function will automatically correct this value.
- fccType: The form type (for RIFF) or list type (for LIST). Required if `MMIO_CREATERIFF` or `MMIO_CREATELIST` is used.
- ulDataOffset: (Output) Filled with the file offset of the start of the data portion.
- ulFlags: (Output) Set to `MMIO_DIRTY` to indicate the chunk was created by this function.
- usFlags (USHORT) - input
- Options for chunk creation:
- MMIO_CREATERIFF: Creates a 'RIFF' chunk. The `fccType` field specifies the form type (e.g., 'WAVE').
- MMIO_CREATELIST: Creates a 'LIST' chunk. The `fccType` field specifies the list type.
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 invalid.
- MMIOERR_CANNOTWRITE: The I/O buffer could not be written to disk, likely due to insufficient space.
Remarks
When mmioCreateChunk is called, it writes the 8-byte header (ID and size) to the file. To finish writing the chunk, the caller should:
- Write the data using mmioWrite.
- Call mmioAscend.
If the size provided in `ckSize` is accurate, mmioAscend can simply move the file pointer to the end of the chunk. If the size is different, mmioAscend must "seek back" to the chunk header to update the `ckSize` field with the actual amount of data written.
Example Code
The following example demonstrates how to create a RIFF 'WAVE' chunk:
HMMIO hmmio1;
MMCKINFO mmckinfo;
USHORT usFlags;
USHORT rc;
/* Initialize structure */
memset( &mmckinfo, '\0', sizeof(MMCKINFO) );
/* Specify the form type for a RIFF chunk */
mmckinfo.fccType = mmioFOURCC('W', 'A', 'V', 'E');
mmckinfo.ckSize = 0; // Size will be corrected later by mmioAscend
/* Create the RIFF chunk */
rc = mmioCreateChunk(hmmio1, &mmckinfo, MMIO_CREATERIFF);
if (rc != MMIO_SUCCESS) {
/* Handle error */
} else {
/* Successfully created and descended into the RIFF chunk */
/* You can now create sub-chunks (like 'fmt ' or 'data') */
}