mmioOpen

The mmioOpen function opens a file for unbuffered or buffered I/O. It is a highly versatile function capable of opening standard DOS files, memory-based files, or elements within custom storage systems (such as RIFF bundles) by utilizing specialized I/O procedures (IOProcs).

Syntax

#define INCL_MMIOOS2
#include <os2.h>

HMMIO mmioOpen(PSZ pszFileName, PMMIOINFO pmmioinfo, ULONG ulOpenFlags);

Parameters

pszFileName (PSZ) - input

The name of the file to open. The format of this string determines how MMIO identifies the handler:

Standard DOS File: If no plus sign (+) is present, it is treated as a normal file.
Compound/Custom File: Uses the format `FILENAME.EXT+ELEMENTNAME`. The extension (e.g., `.BND`) identifies the IOProc. Parsing occurs from right to left.
File Handle: If this is `NULL`, MMIO assumes the `aulInfo[0]` field of `pmmioinfo` contains an already open DOS file handle.
Memory File: If this is `NULL` and `fccIOProc` is `FOURCC_MEM`, a memory file is opened.

pmmioinfo (PMMIOINFO) - input: A pointer to an MMIOINFO structure for advanced options. You can specify a custom IOProc address (`pIOProc`), set buffer sizes (`cchBuffer`), or pass media types. If `NULL`, default values are used.; Note: Always zero-out this structure before use to avoid passing garbage data in reserved fields.

ulOpenFlags (ULONG) - input: Specifies how the file is accessed. Flags can be combined:

Flag	Description
MMIO_READ	Opens for reading only (default).
MMIO_WRITE	Opens for writing only.
MMIO_READWRITE	Opens for both reading and writing (Required for saving Wave files).
MMIO_CREATE	Creates a new file or truncates an existing one to zero length.
MMIO_APPEND	Moves the file pointer to the end of the file immediately after opening.
MMIO_ALLOCBUF	Directs MMIO to internaly allocate an I/O buffer.
MMIO_DELETE	Deletes the file specified in `pszFileName`. Returns `TRUE` on success; do not call mmioClose.
MMIO_EXCLUSIVE	Denies other processes read/write access.
MMIO_DENYNONE	Allows other processes read/write access (default).

Return Value

hmmio (HMMIO): Returns an MMIO file handle on success. This handle is **not** compatible with standard OS/2 `DosRead` or `DosWrite` calls.; Returns `NULL` if the file cannot be opened. Check `pmmioinfo->ulErrorRet` or call mmioGetLastError for specific error codes (e.g., `MMIOERR_DELETE_FAILED`).

Remarks

If the pmmioinfo parameter is provided the following fields must be filled in by the caller as described:

fccIOProc: If this field is not NULL, it is the four character code of an installed I/O procedure that will handle I/O. If fccIOProc and pIOProc are NULL, mmioOpen determines which I/O procedure to use based on the syntax of the pszFileName parameter. (See description of pszFileName.) If fccIOProc is NULL, but pIOProc is not NULL, the custom I/O procedure (pIOProc) is used. This I/O procedure does not need to be installed using mmioInstallIOProc.

The following I/O procedure identifiers are defined:

FOURCC_DOS: pszFileName is assumed to be either the name of a DOS file (which is to be opened using the file system opening procedure), or aulInfo contains the DOS file handle of an open file handle (directed to a PSZ).

FOURCC_BND: A RIFF compound file element is opened. This procedure calls mmioCFOpen if necessary to read the CTOC into memory before the element can be accessed.

If MMIO_CREATE or MMIO_APPEND is specified when opening an element, the system automatically accesses the element as exclusive until the element is closed.

FOURCC_MEM: A memory file is opened. The pszFileName parameter should be NULL. There are two ways to set up a memory file:

The pchBuffer field points to a caller-supplied memory buffer, and the cchBuffer field indicates the size of the buffer. The memory file can be read and written like an ordinary file, but the file can not be expanded larger than the number of bytes specified in cchBuffer. If the MMIO_CREATE flag is specified, the end of the file is initially at the beginning of the buffer. If MMIO_CREATE is NULL, the user specifies in aulInfo[1] the number of bytes of data in the memory buffer. For the default case, where aulInfo[1] is 0, the end of the file is set to the end of the buffer.

mmioOpen can allocate the memory block for the memory file. The cchBuffer field is the desired initial size of the memory I/O buffer. The aulInfo[0] field must be the number of bytes by which to expand the memory file if the initial buffer becomes filled. The MMIO_CREATE flag must be specified. The end of the file is initially at the beginning of the buffer, and if the memory file must be expanded, it is expanded at least aulInfo[0] bytes at a time. If aulInfo[0] is 0, the buffer cannot expand. There is no default for cchBuffer when used to open a memory file.

The pIOProc field uses a custom I/O procedure defined in this field. Set the fccIOProc field to NULL, and set the pIOProc field to the address of the custom I/O procedure to use. Otherwise, pIOProc must be zero.

cchBuffer specifies the size of the memory block to use as an I/O buffer or as a memory file. See descriptions of pchBuffer and the MMIO_ALLOCBUF flag for more information.

The pchBuffer field points to a caller-provided memory buffer to use as an I/O buffer or as a memory file. The cchBuffer field must be the size of the buffer. If the caller-provided memory buffer is not provided, pchBuffer must be NULL.

To open a memory file that performs I/O on an already allocated memory block, set the pszFileName parameter to NULL, the fccIOProc field to FOURCC_MEM, the pchBuffer field to point to the memory buffer, the cchBuffer field to the size of the memory buffer, the ulOpenFlags parameter to MMIO_READWRITE (plus MMIO_CREATE if the memory file is initially empty), and set all other fields of the MMIOINFO structure passed in the pmmioinfo parameter to zero.

For example, to open a memory file that is initially 32KB in size, but can be expanded at least 16KB at a time:

           Set aulInfo[0] = 16K 2.
               Set cBytes =16K 3.
               Set pszFileName to NULL 4.
               Set fccIOProc to FOURCC_MEM 5.
               Set ulOpenFlags to indicate MMIO_READWRITE plus MMIO_CREATE 6.
               Set other fields of pmmioinfo to zero

Initially this file will be empty.

A system-allocated memory buffer must be opened as MMIO_READWRITE, which is the default for that case. If this does not happen, the open-a-memory file process fails.

If both a user buffer is specified, and an expansion size is requested, the open-a-memory file process fails because it is not possible to later expand the buffer size in this situation.

As with DOS file handles, different applications cannot share a single hmmio. In other words, MMIO handles (HMMIO) are unique to a process.

Example Code

This example demonstrates opening a Wave file contained within a compound bundle file.

   HMMIO hmmio1;
   MMIOINFO mmioinfo;
   ULONG ulFlags;

   /* Initialize structure */
   memset(&mmioinfo, '\0', sizeof(MMIOINFO));
   
   /* Explicitly request the WAVE I/O procedure */
   mmioinfo.fccIOProc = FOURCC_WAVE;
   
   /* Set access and sharing flags */
   ulFlags = MMIO_READ | MMIO_DENYNONE;

   /* Open an element 'train.wav' inside the bundle 'sounds.bnd' */
   hmmio1 = mmioOpen("sounds.bnd+train.wav", &mmioinfo, ulFlags);

   if (!hmmio1) {
      /* Use mmioGetLastError() to diagnose */
   } else {
      /* Perform I/O operations */
      mmioClose(hmmio1, 0);
   }

Related Functions