mmioCFClose

The mmioCFClose function closes a compound file that was previously opened by mmioCFOpen. It manages the in-memory Table of Contents (CTOC) and ensures data integrity by committing changes to disk.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

ULONG mmioCFClose(HMMCF hmmcf, ULONG ulFlags);

Parameters

hmmcf (HMMCF) - input

A RIFF compound-file handle returned by mmioCFOpen.

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 provided handle is not valid.
• MMIO_CF_FAILURE: The function failed. A call to mmioGetLastError may return:

• MMIOERR_CF_NON_BND_FILE: Attempted to close a file that is not a RIFF compound file.
• MMIOERR_CF_ELEMENTS_OPEN: One or more compound-file elements are still open.
• MMIOERR_INTERNAL_SYSTEM: The operation failed due to an internal system error.

Remarks

This function decrements the usage count of the CTOC maintained in memory for the specified RIFF compound file. When the usage count reaches zero:

1. If the file was not opened as read-only, the CTOC is written to disk.
2. The RIFF compound-file handle is closed.

Important Restrictions:

• This function will fail if any individual elements within the compound file are still open via mmioOpen. All elements must be closed before the main compound file can be closed.
• You must use mmioCFClose specifically for compound files; using standard mmioClose on an `HMMCF` handle will result in an error.
• In the event of an ExitList close, the system will automatically close all open elements to allow the `mmioCFClose` to complete.
• If the function fails after elements in the Resource Group (CGRP) have been modified, the file structure may be inconsistent. Users should ensure there is sufficient disk space and attempt the close operation again.

Example

HMMCF hmmcf1;
ULONG ulFlags = 0;
ULONG rc;

// ... perform compound file operations ...

rc = mmioCFClose(hmmcf1, ulFlags);

if (rc != MMIO_CF_SUCCESS) {
    /* Handle the error, such as checking for open elements */
}