mmioCFCompact
The mmioCFCompact function compacts the elements of a RIFF compound file by removing elements marked for deletion and reclaiming the unused space.
Syntax
#define INCL_MMIOOS2 #include <os2.h> ULONG mmioCFCompact(PSZ pszFileName, ULONG ulFlags);
Parameters
- pszFileName (PSZ) - input
- The name of the RIFF compound file to be compacted.
- ulFlags (ULONG) - input
- Reserved for future use and must be set to zero.
Return Values
- rc (ULONG)
- Returns the result of the operation:
- MMIO_SUCCESS: Function succeeded (0).
- MMIO_ERROR: The open failed. This may occur if the file name does not exist or if the file is already open by another process.
- MMIOERR_INVALID_FILENAME: No file name was specified.
- MMIOERR_INTERNAL_SYSTEM: An internal system error has occurred.
- MMIOERR_NO_CORE: Sufficient memory could not be allocated for the operation buffer.
Remarks
The mmioCFCompact function does not apply data compression algorithms. Instead, it performs the following structural maintenance:
- It identifies elements in the Compound-file Resource-Group (CGRP) where the `ulMedType` field in the MMCTOCENTRY is marked as `FOURCC_DEL`.
- It removes these elements and updates their status to `FOURCC_FREE`.
- It sorts the remaining Table of Contents (CTOC) entries according to their data offsets. Note that this order may change if subsequent append operations are performed.
Caution: This function performs compaction in place. It rewrites the file within the same storage space to conserve memory. If an error occurs (such as a power failure or system crash) during the compaction process, the original file data may be lost or corrupted with no way to salvage it.
If data safety is a priority, consider using mmioCFCopy instead. mmioCFCopy also compacts the file but writes the results to a new target file, leaving the source file untouched until the operation is confirmed successful.
Example
PSZ pszFileName;
ULONG ulFlags;
ULONG ulReturnCode;
pszFileName = "SOUNDS.BND";
ulFlags = 0L;
ulReturnCode = mmioCFCompact(pszFileName, ulFlags);
if (ulReturnCode) {
/* Handle compaction error */
} else {
/* File compacted successfully */
}