MmioCFAddElement

The mmioCFAddElement function adds a data element to the Compound-file Resource-Group (CGRP) chunk of an open RIFF compound file. It handles the low-level details of seeking, writing data, and updating the Table of Contents (CTOC).

Syntax

#define INCL_MMIOOS2
#include <os2.h>

ULONG mmioCFAddElement(HMMCF hmmcf, PSZ pszElementName, FOURCC fccType, 
                       PCHAR pchBuffer, LONG cchBytes, ULONG ulFlags);

Parameters

hmmcf (HMMCF) - input

A RIFF compound-file handle returned by mmioCFOpen.

pszElementName (PSZ) - input

A pointer to the name of the element to be added. Element names follow DOS naming conventions; the symbols `+` and `|` are invalid.

fccType (FOURCC) - input

The four-character code (FOURCC) identifying the element type.

pchBuffer (PCHAR) - input

A pointer to the caller-supplied buffer containing the actual element data.

cchBytes (LONG) - input

The length (in bytes) of the data in `pchBuffer`.

ulFlags (ULONG) - input

Options for the operation. Can be 0 or:

• MMIO_CF_ENTRY_EXISTS: Set this only if the CTOC entry for this element already exists.

Return Values

rc (ULONG)

Returns the result of the operation:

• MMIO_CF_SUCCESS: Function succeeded (0).
• MMIOERR_INVALID_HANDLE: The provided `hmmcf` is not a valid handle.
• MMIOERR_INVALID_PARAMETER: A null pointer was passed for name or buffer, or length was invalid.
• MMIOERR_READ_ONLY_FILE: The file was opened in read-only mode.
• MMIO_CF_FAILURE: General failure. Detailed error may be retrieved via `mmioGetLastError`.

Remarks

The function automatically creates a Table of Contents (CTOC) entry if one does not exist. It appends the element data to the end of the Resource Group (CGRP) chunk and updates all necessary RIFF chunk sizes.

This function is intended for adding existing data from a buffer to a compound file. If you need to create a new element and write to it dynamically (like a standard file), use mmioOpen with the `MMIO_CREATE` flag and the `compound.bnd+element` naming syntax.

Manual replication of this function would require:

1. Seeking to the start of the RIFF file.
2. Descending into the `BND` and `CGRP` chunks.
3. Writing data at the end of `CGRP`.
4. Ascending and correcting chunk sizes.
5. Calling `mmioCFChangeEntry` or `mmioCFAddEntry` to update the CTOC.

Example

HMMCF hmmcf1;
FOURCC fcctype = FOURCC_FOO;
CHAR *pchBuffer; // Assume this contains data
LONG cchBuffer = 1024;
ULONG rc;

rc = mmioCFAddElement(hmmcf1, "myelement.foo", fcctype, 
                       pchBuffer, cchBuffer, 0);

if (rc == MMIO_CF_SUCCESS) {
    // Element added successfully
}