mmioOpen

Syntax

HMMIO mmioOpen(szFilename, lpmmioinfo, dwOpenFlags)

This function opens a file for unbuffered or buffered I/O. The file can be a DOS file, a memory file, or an element of a custom storage system.

Parameters

LPSTR szFilename

Specifies a far pointer to a string containing the filename of the file to open. If no I/O procedure is specified to open the file, then the filename determines how the file is opened, as follows:

If the filename does not contain “+”, then it is assumed to be the name of a DOS file.

If the filename is of the form “foo.ext+bar”, then the extension “EXT ” is assumed to identify an installed I/O procedure which is called to perform I/O on the file (see mmioInstallIOProc).

If the filename is NULL and no I/O procedure is given, then adwInfo[0] is assumed to be the DOS file handle of a currently open file.

The filename should not be longer than 128 bytes, including the terminating NULL.

When opening a memory file, set szFilename to NULL.

LPMMIOINFO lpmmioinfo

Specifies a far pointer to an MMIOINFO structure containing extra parameters used by mmioOpen. Unless you are opening a memory file, specifying the size of a buffer for buffered I/O, or specifying an uninstalled I/O procedure to open a file, this parameter should be NULL.

If lpmmioinfo is not NULL, all unused fields of the MMIOINFO structure it references must be set to zero, including the reserved fields.

DWORD dwOpenFlags

Specifies option flags for the open operation. The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually exclusive—only one should be specified. The MMIO_COMPAT, MMIO_EXCLUSIVE, MMIO_DENYWRITE, MMIO_DENYREAD, and MMIO_DENYNONE flags are DOS file-sharing flags, and can only be used after the DOS command SHARE has been executed.

MMIO_READ

Opens the file for reading only. This is the default, if MMIO_WRITE and MMIO_READWRITE are not specified.

MMIO_WRITE

Opens the file for writing. You should not read from a file opened in this mode.

MMIO_READWRITE

Opens the file for both reading and writing.

MMIO_CREATE

Creates a new file. If the file already exists, it is truncated to zero length. For memory files, MMIO_CREATE indicates the end of the file is initially at the start of the buffer.

MMIO_DELETE

Deletes a file. If this flag is specified, szFilename should not be NULL. The return value will be TRUE (cast to HMMIO) if the file was deleted successfully, FALSE otherwise. Do not call mmioClose for a file that has been deleted. If this flag is specified, all other flags are ignored.

MMIO_ALLOCBUF

Opens a file for buffered I/O. To allocate a buffer larger or smaller than the default buffer size (8K), set the cchBuffer field of the MMIOINFO structure to the desired buffer size. If cchBuffer is zero, then the default buffer size is used. If you are providing your own I/O buffer, then the MMIO_ALLOCBUF flag should not be used.

MMIO_COMPAT

Opens the file with compatibility mode, allowing any process on a given machine to open the file any number of times. mmioOpen fails if the file has been opened with any of the other sharing modes.

MMIO_EXCLUSIVE

Opens the file with exclusive mode, denying other processes both read and write access to the file. mmioOpen fails if the file has been opened in any other mode for read or write access, even by the current process.

MMIO_DENYWRITE

Opens the file and denies other processes write access to the file. mmioOpen fails if the file has been opened in compatibility or for write access by any other process.

MMIO_DENYREAD

Opens the file and denies other processes read access to the file. mmioOpen fails if the file has been opened in compatibility mode or for read access by any other process.

MMIO_DENYNONE

Opens the file without denying other processes read or write access to the file. mmioOpen fails if the file has been opened in compatibility mode by any other process.

Return Value

The return value is a handle to the opened file. This handle is not a DOS file handle—do not use it with any file I/O functions other than MMIO functions.

If the file cannot be opened, the return value is NULL. If lpmmioinfo is not NULL, then its wError field will contain extended error information returned by the I/O procedure.

Comments

If lpmmioinfo references an MMIOINFO structure, set up the fields as described below. All unused fields must be set to zero, including reserved fields.

To request that a file be opened with an installed I/O procedure, set the fccIOProc field to the four-character code of the I/O procedure, and set the pIOProc field to NULL.

To request that a file be opened with an uninstalled I/O procedure, set the pIOProc field to point to the I/O procedure, and set fccIOProc to NULL.

To request that mmioOpen determine which I/O procedure to use to open the file based on the filename contained in szFilename, set both fccIOProc and pIOProc to NULL. This is the default behavior if no MMIOINFO structure is specified.

To open a memory file using an internally allocated and managed buffer, set the pchBuffer field to NULL, fccIOProc to FOURCC_MEM, cchBuffer to the initial size of the buffer, and adwInfo[0] to the incremental expansion size of the buffer. This memory file will automatically be expanded in increments of adwInfo[0] bytes when necessary. Specify the MMIO_CREATE flag for the dwOpenFlags parameter to initially set the end of the file to be the beginning of the buffer.

To open a memory file using a caller-supplied buffer, set the pchBuffer field to point to the memory buffer, fccIOProc to FOURCC_MEM, cchBuffer to the size of the buffer, and adwInfo[0] to the incremental expansion size of the buffer. The expansion size in adwInfo[0] should only be non-zero if pchBuffer is a pointer obtained by calling GlobalAlloc and GlobalLock, since GlobalReAlloc will be called to expand the buffer. In particular, if pchBuffer points to a local or global array, a block of memory in the local heap, or a block of memory allocated by GlobalDosAlloc, adwInfo[0] must be zero.

Specify the MMIO_CREATE flag for the dwOpenFlags parameter to initially set the end of the file to be the beginning of the buffer; otherwise, the entire block of memory will be considered readable.

To use a currently open DOS file handle with MMIO, set the fccIOProc field to FOURCC_DOS, pchBuffer to NULL, and adwInfo[0] to the DOS file handle. Note that offsets within the file will be relative to the beginning of the file, and will not depend on the DOS file position at the time mmioOpen is called; the initial MMIO offset will be the same as the DOS offset when mmioOpen is called. Later, to close the MMIO file handle without closing the DOS file handle, pass the MMIO_FHOPEN flag to mmioClose.

You must call mmioClose to close a file opened with mmioOpen. Open files are not automatically closed when an application exits.

See Also

mmioClose