mmioCFCopy
The mmioCFCopy function copies the Table of Contents (CTOC) and Resource Group (CGRP) chunks from an open RIFF compound file to a new destination file. During this process, the data is automatically compacted, meaning deleted elements are not transferred to the new file.
Syntax
#define INCL_MMIOOS2 #include <os2.h> ULONG mmioCFCopy(HMMCF hmmcfSource, PSZ pszDestFileName, ULONG ulFlags);
Parameters
- hmmcfSource (HMMCF) - input
- A RIFF compound-file handle returned by mmioCFOpen. This represents the source file to be copied.
- pszDestFileName (PSZ) - input
- A pointer to the string containing the name of the destination file.
- ulFlags (ULONG) - input
- Reserved for future use and must be set to zero.
Return Values
- rc (ULONG)
- Returns the result of the operation:
- MMIO_CF_SUCCESS: Function succeeded (0).
- MMIOERR_INVALID_HANDLE: The source handle passed was not valid.
- MMIOERR_INVALID_PARAMETER: The destination file name was NULL, or an attempt was made to copy the file to itself.
- MMIOERR_READ_ONLY_FILE: The source RIFF compound file is opened as read-only.
- MMIO_CF_FAILURE: The operation failed. A call to mmioGetLastError may return:
- MMIOERR_CF_ELEMENTS_OPEN: One or more compound-file elements are currently open.
- MMIOERR_NO_CORE: Not enough memory is available for the copy buffer.
- MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.
Remarks
The mmioCFCopy function performs a "clean" copy of a compound file. It creates the target file using mmioOpen with the `MMIO_CREATE` flag, writes a new RIFF BND header, and then transfers the CTOC and CGRP chunks. Because deleted elements (marked with `FOURCC_DEL`) are skipped, the resulting file is smaller and more efficient than a simple file-system copy.
Key operational details:
- Data Integrity: If the copy operation fails at any point, the partially written target file is automatically deleted to prevent corrupted files.
- Source Safety: The source file remains unaltered. Unlike mmioCFCompact, this is a safe way to reclaim space without risking the original file.
- Overwrite Behavior: If the destination file already exists, it will be overwritten.
- Restrictions: The destination file must not be open when this function is called. Additionally, copying a file to itself is invalid.
- Performance: The system optimizes the copy by either using a single large buffer or fixed page-size blocks, depending on the file's total size.
Example
HMMCF hmmcfSource;
PSZ pszDestFileName = "BACKUP.BND";
ULONG ulFlags = 0;
ULONG rc;
/* Assume hmmcfSource was obtained via mmioCFOpen */
rc = mmioCFCopy(hmmcfSource, pszDestFileName, ulFlags);
if (rc == MMIO_CF_SUCCESS) {
/* Copy and compaction complete */
} else {
/* Handle error; source file is still intact */
}