| HMMIO mmioOpen(szFilename, lpmmioinfo, dwOpenFlags) | |||
| LPSTR szFilename; | |||
| LPMMIOINFO lpmmioinfo; | |||
| DWORD dwOpenFlags; |
The mmioOpen 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.
szFilename
Specifies a 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
Specifies a 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.
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.
| Value | Meaning |
| 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 file opening flags are ignored. | ||
| MMIO_PARSE | ||
| Creates a fully qualified filename from the path specified in szFileName. The fully qualified filename is placed back into szFileName. The return value will be TRUE (cast to HMMIO) if the qualification was successful, FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. If this flag is specified, all other file opening flags are ignored. | ||
| MMIO_EXIST | ||
| Determines whether the specified file exists and creates a fully qualified filename from the path specified in szFileName. The fully qualified filename is placed back into szFileName. The return value will be TRUE (cast to HMMIO) if the qualification was successful and the file exists, FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. | ||
| 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. | ||
| MMIO_GETTEMP | ||
| Creates a temporary filename, optionally using the parameters passed in szFileName to determine the temporary name. For example, you can specify “C:F” to create a temporary file residing on drive C, starting with letter “F”. The resulting filename is placed in the buffer pointed to by szFileName. The return value will be TRUE (cast to HMMIO) if the temporary filename was created successfully,FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. This flag overrides all other flags. | ||
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 wErrorRet field will contain extended error information returned by the I/O procedure.
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.
mmioClose