mmioCFOpen

The mmioCFOpen function opens a RIFF compound file by name. It manages the Table of Contents (CTOC) in memory, ensuring that multiple processes or calls can share access to the same compound file structure efficiently.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

HMMCF mmioCFOpen(PSZ pszFileName, PMMCFINFO pmmcfinfo, PMMIOINFO pmmioinfo, ULONG ulFlags);

Parameters

pszFileName (PSZ) - input

The name of the RIFF compound file to open. The name cannot contain the characters + or | as these are reserved for expressing paths to specific elements within a compound file.

pmmcfinfo (PMMCFINFO) - input

A pointer to an MMCFINFO structure containing optional header information. This can be NULL if no special header info is required.

pmmioinfo (PMMIOINFO) - input

A pointer to an MMIOINFO structure. This structure contains optional information that is passed internally to the mmioOpen call. This can be NULL.

ulFlags (ULONG) - input

Specifies how the file should be opened. Access and sharing flags are mutually exclusive within their groups.

Group	Flag	Description
Access	MMIO_READ	Opens the file for reading only (Default).
	MMIO_WRITE	Opens the file for writing only (cannot be read).
	MMIO_READWRITE	Opens the file for both reading and writing.
Sharing	MMIO_EXCLUSIVE	Denies other processes both read and write access.
	MMIO_DENYWRITE	Denies other processes write access.
	MMIO_DENYREAD	Denies other processes read access.
	MMIO_DENYNONE	Allows other processes any access.
Action	MMIO_CREATE	Directs mmioCFOpen to create a new file. If it exists, it is truncated to 0 length unless already open.

Return Values

hmmcf (HMMCF)

Returns a handle to the opened RIFF compound file if successful. Returns NULL if the file could not be opened.

Remarks

This function is the primary gatekeeper for compound file access:

• CTOC Management: Only one CTOC for a particular compound file is maintained in memory at a time. This CTOC is shared by any process needing access. If the file is already open, it returns the existing handle and checks access/sharing compatibility.
• BND Files: The function determines if the CTOC is already in memory; if not, it constructs one. If the file is not a valid BND file, an error is returned.
• Element Access: Individual elements within the compound file can be opened by passing the element name to the mmioOpen function.
• FOURCC Usage: The FOURCC of `FOURCC_BND` should be used only for elements, not for the compound file itself. Do not specify `FOURCC_BND` when calling mmioCFOpen.

Related Functions

• mmioCFClose
• mmioOpen

Example Code

The following code illustrates how to open a RIFF compound file:

   HMMCF hmmcf1;
   MMCFINFO mmcfinfo;
   MMIOINFO mmioinfo;
   ULONG ulFlags;
   char pFileName[CCHMAXPATH];

   memset( &mmcfinfo, '\0', sizeof(MMCFINFO));
   memset( &mmioinfo, '\0', sizeof(MMIOINFO));
   strcpy( pFileName, "myfile.bnd" );
   ulFlags = MMIO_READWRITE | MMIO_DENYWRITE;

   hmmcf1 = mmioCFOpen( pFileName, &mmcfinfo, &mmioinfo, ulFlags);
   if (!hmmcf1) {
      /* Handle error */
   } else {
      /* Proceed with compound file operations */
   }