mmioCFAddEntry

The mmioCFAddEntry function adds a new entry to the compound-file Table of Contents (CTOC) chunk of an open RIFF compound file. This function modifies the CTOC in memory; changes are written to the disk when the file is closed.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

ULONG mmioCFAddEntry(HMMCF hmmcf, PMMCTOCENTRY pmmctocentry, ULONG ulFlags);

Parameters

hmmcf (HMMCF) - input

A RIFF compound-file handle returned by mmioCFOpen.

pmmctocentry (PMMCTOCENTRY) - input

A pointer to a user-supplied MMCTOCENTRY structure containing the entry details. Because the element name is appended to this structure, it is variable in size. You must ensure enough memory is allocated to hold both the structure and the name.

ulFlags (ULONG) - input

Reserved for future use. This must be set to 0.

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.
• MMIOERR_INVALID_PARAMETER: The `pmmctocentry` pointer is NULL.
• MMIOERR_READ_ONLY_FILE: The file was opened in read-only mode.
• MMIO_CF_FAILURE: General failure. Call `mmioGetLastError` for specifics:

• MMIOERR_CF_DUPLICATE_SEEN: An entry with this element name already exists.
• MMIOERR_NO_CORE: Insufficient memory to expand the CTOC.
• MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.

Remarks

The element name serves as the unique identifier for the entry and is not case-sensitive.

Unlike `mmioCFAddElement`, this function only modifies the **in-memory** representation of the CTOC. It does not perform any file I/O or expand the physical RIFF file at the time of the call. If the number of entries grows beyond the space originally allocated in the file, the entire CTOC will be relocated and written after the Resource Group (CGRP) chunk when mmioCFClose is called.

Duplicate entries (names that already exist in the CTOC) are strictly prohibited and will result in an error.

Example

HMMCF hmmcf1;
MMCTOCENTRY mmctocentry;
ULONG rc;

// Note: In practice, ensure the structure is properly initialized 
// and the element name is appended to the memory block.
rc = mmioCFAddEntry(hmmcf1, &mmctocentry, 0);

if (rc == MMIO_CF_SUCCESS) {
    // Entry added to the in-memory CTOC
} else if (rc == MMIOERR_CF_DUPLICATE_SEEN) {
    // Handle duplicate name error
}