mmioCFChangeEntry

The mmioCFChangeEntry function modifies an existing compound-file Table of Contents (CTOC) entry in an open RIFF compound file.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

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

Parameters

hmmcf (HMMCF) - input

A RIFF compound-file handle returned by mmioCFOpen.

pmmctocentry (PMMCTOCENTRY) - input

A pointer to the MMCTOCENTRY structure containing the modified CTOC data. This structure is variable in size; the user must ensure enough memory has been allocated for the structure and the appended element name.

ulFlags (ULONG) - input

Specifies options for the operation. Contains 0 or the following flag:

• MMIO_CHANGEDELETED: Allows a deleted CTOC entry to be changed.

Return Values

rc (ULONG)

Returns the result of the operation:

• MMIO_CF_SUCCESS: Function succeeded (0).
• MMIOERR_INVALID_HANDLE: The handle passed was not valid.
• MMIOERR_INVALID_PARAMETER: The `pmmctocentry` pointer is NULL.
• MMIOERR_READ_ONLY_FILE: The RIFF compound file is opened as read-only.
• MMIO_CF_FAILURE: The function failed. Detailed error codes in the `ulErrorRet` field of the MMIOINFO structure may include:

• MMIOERR_CF_ENTRY_NOT_FOUND: The CTOC entry corresponding to the element name was not found.
• MMIOERR_INTERNAL_SYSTEM: The operation failed due to an internal system error.

Remarks

The identifier for the entry is the element name, which is appended to the end of the MMCTOCENTRY structure. Note that the element name itself cannot be modified using this function; it is used only to locate the existing entry.

When updating entry data:

• If the compression technique is changed, the `ulUncompressBytes` field must be updated accordingly.
• If the compression technique is NULL, `ulUncompressBytes` must represent the uncompressed size of the element in bytes.

It is recommended to call mmioCFFindEntry to populate the MMCTOCENTRY structure with current data before making modifications and calling this function.

Example

HMMCF hmmcf1;
MMCTOCENTRY mmctocentry;
ULONG ulFlags = 0;
ULONG rc;

// Initialize structure
memset(&mmctocentry, '\0', sizeof(MMCTOCENTRY));

// In a real scenario, you would populate mmctocentry with 
// an existing element name and the new metadata.
rc = mmioCFChangeEntry(hmmcf1, &mmctocentry, ulFlags);

if (rc) {
    /* Handle error */
} else {
    /* Entry successfully modified in memory */
}