mmioCFGetInfo

The mmioCFGetInfo function retrieves the compound-file Table of Contents (CTOC) header of an open RIFF compound file. This header contains structural information about how the compound file is organized.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

ULONG mmioCFGetInfo(HMMCF hmmcf, PMMCFINFO pmmcfinfo, ULONG cBytes);

Parameters

hmmcf (HMMCF) - input

A RIFF compound-file handle returned by mmioCFOpen.

pmmcfinfo (PMMCFINFO) - in/out

A pointer to the MMCFINFO data structure that will be filled with the CTOC header. This structure is variable in size because it is followed by variable-length arrays (`aulExHdrFldUsage`, `aulExEntFldUsage`, and `aulExHdrField`).

cBytes (ULONG) - input

The size of the buffer pointed to by `pmmcfinfo`. This represents the maximum number of bytes to be copied.

Return Values

rc (ULONG)

Returns the number of bytes copied if the function succeeds. It returns NULL (0) if the function fails. Detailed error information is stored in the `ulErrorRet` field of the MMIOINFO structure:

• MMIOERR_INVALID_PARAMETER: An invalid parameter was passed (e.g., `pmmcfinfo` is NULL or `cBytes` is 0).
• MMIOERR_WRITE_ONLY_FILE: The file was not opened in a mode that allows reading.
• MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.

Remarks

Because the CTOC header is variable in length, you typically need to make two calls to this function to retrieve the data safely:

1. **First Call:** Call `mmioCFGetInfo` with `cBytes` set to `sizeof(ULONG)`. The first field of the `MMCFINFO` structure is `ulHeaderSize`.
2. **Allocation:** Use the value returned in `ulHeaderSize` to allocate a buffer large enough to hold the entire header.
3. **Second Call:** Call `mmioCFGetInfo` again using the allocated buffer and the full size.

The information retrieved includes the base MMCFINFO structure followed by specific arrays defining extra header and entry field usage.

Example

HMMCF     hmmcf1;
PMMCFINFO pmmcfinfo;
ULONG     cBytes;
ULONG     rc;

/* 1. Get the size of the header first */
rc = mmioCFGetInfo(hmmcf1, (PMMCFINFO)&cBytes, sizeof(ULONG));

if (rc == sizeof(ULONG)) {
    /* 2. Allocate memory based on the size retrieved (cBytes) */
    pmmcfinfo = (PMMCFINFO)malloc(cBytes);
    
    if (pmmcfinfo) {
        /* 3. Retrieve the full CTOC header */
        rc = mmioCFGetInfo(hmmcf1, pmmcfinfo, cBytes);
        if (rc == 0) {
            /* Handle error */
        }
        free(pmmcfinfo);
    }
}

Related Functions

• mmioCFSetInfo