mmioCFSetInfo

The mmioCFSetInfo function modifies the information stored in the compound-file table of contents (CTOC) header of an open RIFF compound file.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

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

Parameters

hmmcf (HMMCF) - input

A RIFF compound-file handle returned by mmioCFOpen.

pmmcfinfo (PMMCFINFO) - input

A pointer to the MMCFINFO data structure containing the modified CTOC header. Typically, this buffer is first populated using mmioCFGetInfo and then modified before being passed to this function.

cBytes (ULONG) - input

The size of the buffer pointed to by the pmmcfinfo parameter. This specifies the maximum number of bytes to be copied into the CTOC header.

Return Values

rc (ULONG)

Returns the number of bytes copied if the function succeeds. If the function fails, it returns NULL (0). Detailed error information can be retrieved via mmioGetLastError, which may return:

• MMIOERR_INVALID_PARAMETER: The pmmcfinfo parameter is NULL or cBytes is not greater than 0.
• MMIOERR_READ_ONLY_FILE: The file was not opened in a mode that allows writing (e.g., it is read-only).
• MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.

Remarks

Users should exercise caution when modifying the CTOC header. Generally, the only fields that should be modified are the aulExHdrFldUsage and aulExHdrField fields, which are appended to the end of the MMCFINFO structure. Modifying structural management fields directly may corrupt the compound file's integrity.

Related Functions

• mmioCFGetInfo
• mmioCFOpen

Example Code

The following code illustrates how to retrieve, modify, and then set the CTOC header information:

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

   /* First, determine the size of the CTOC header */
   rc = mmioCFGetInfo(hmmcf1, (PMMCFINFO)&cBytes, sizeof(ULONG));
   if (rc != sizeof(ULONG)) {
       /* Handle error */
   } else {
       /* Allocate memory for the full header */
       pmmcfinfo = (PMMCFINFO)malloc(cBytes);
       if (pmmcfinfo) {
           /* Retrieve the actual data */
           mmioCFGetInfo(hmmcf1, pmmcfinfo, cBytes);

           /* ... Modify aulExHdrFldUsage or aulExHdrField here ... */

           /* Update the CTOC header in the file */
           rc = mmioCFSetInfo(hmmcf1, pmmcfinfo, pmmcfinfo->ulHeaderSize);
           if (!rc) {
               /* Handle error */
           }
           free(pmmcfinfo);
       }
   }