Before doing any I/O operations to a file, you must first open the file using the mmioOpen function. The mmioOpen function returns a file handle which you use to identify the open file when calling other file I/O functions. The mmioOpen function has the following syntax:
HMMIO mmioOpen(szFileName, lpmmioinfo, dwFlags)
The szFileName parameter points to a null-terminated string containing the path of the file to open.
The lpmmioinfo parameter is a far pointer to an MMIOINFO structure containing additional parameters. For basic file I/O services, this parameter should be NULL.
The dwFlags parameter specifies options for opening the file. The most commonly used flags for basic file I/O are MMIO_READ, MMIO_WRITE, and MMIO_CREATE.
The return value is a file handle of type HMMIO. Use this file handle to identify the open file when calling other file I/O functions. If the file cannot be opened, the return value is NULL.
Warning:
An HMMIO file handle is not a MS-DOS file handle. Do not use HMMIO file handles with MS-DOS, Windows, or C run-time file I/O functions.
There are options you can use with the mmioOpen function for operations beyond basic file I/O. By specifying an MMIOINFO structure with the lpmmioinfo parameter, you can open memory files, specify a custom I/O procedure, or supply a buffer for buffered I/O. These topics are discussed later in this chapter. First, this chapter discusses the most basic use of mmioOpen—opening files for basic unbuffered file I/O.
To open a file for basic I/O operations, set the lpmmioinfo parameter of mmioOpen to NULL. For example, the following code fragment opens a file named “C:\SAMPLES\SAMPLE1.TXT” for reading, and checks the return value for errors:
HMMIO hFile;
.
.
.
if ((hFile = mmioOpen("C:\\SAMPLES\\SAMPLE1.TXT",
NULL, MMIO_READ)) != NULL) /* File opened successfully */
else
/* File cannot be opened */
When you open a file, you must specify whether you are opening the file for reading, writing, or both reading and writing. In addition, you can specify other options, such as to create or delete a new file. Use the dwFlags parameter of mmioOpen to specify options for opening a file.
The following table lists the basic options for opening a file using mmioOpen:
| Flag | Description |
| MMIO_READ | Opens a file for reading only. |
| MMIO_WRITE | Opens a file for writing only. |
| MMIO_READWRITE | Opens a file for reading and writing. |
| MMIO_CREATE | Creates a new file (if the file already exists, it truncates it to zero length). |
| MMIO_DELETE | Deletes a file. |
| MMIO_ALLOCBUF | Opens a file for buffered I/O. |
The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are read/write privilege flags. These flags are mutually exclusive—specify only one when opening a file. If you don't specify one of these flags, mmioOpen opens the file for reading only.
The MMIO_CREATE and MMIO_DELETE flags are also mutually exclusive. You can specify one of the read/write privilege flags with the MMIO_CREATE flag. You can't specify any additional flags with the MMIO_DELETE flag.
For information on using the MMIO_ALLOCBUF flag, see “Performing Buffered File I/O,” later in this chapter.
For a complete list of the mmioOpen flags, see the mmioOpen function entry in the Multimedia Programmer's Reference.
In addition to the basic options for opening a file, there are sharing options you can use for opening MS-DOS files so they can be opened and accessed by more than one process. The following table lists the sharing options for opening a file using mmioOpen.
| Flag | Description |
| MMIO_COMPAT | Opens a file in compatibility mode. |
| MMIO_EXCLUSIVE | Opens a file in exclusive mode. |
| MMIO_DENYWRITE | Opens a file and denies other processes write access to the file. |
| MMIO_DENYREAD | Opens a file and denies other processes read access to the file. |
| MMIO_DENYNONE | Opens a file without denying other processes read or write access to the file. |
The sharing options are rarely used by applications, and are provided only because they are available through MS-DOS. They are not available for memory files or for files opened using custom I/O procedures. For more information on sharing options, see the Microsoft MS-DOS Programmer's Reference or the Microsoft MS-DOS Encyclopedia.
Note:
Sharing options are ignored unless the user has run the MS-DOS share command.