| HFILE OpenFile(lpszFile, lpOpenBuff, fuMode) | |||||
| LPCSTR lpszFile; | /* address of filename | */ | |||
| LPOFSTRUCT lpOpenBuff; | /* address of buffer for file information | */ | |||
| UINT fuMode; | /* action and attributes | */ | |||
The OpenFile function creates, opens, reopens, or deletes a file.
This function is provided primarily for compatibility with Windows 3.1. New Win32 applications should use the CreateFile function. In particular, the OpenFile function cannot be used to open a named pipe; the CreateFile function should be used.
lpszFile
Points to a null-terminated string that names the file to be opened. The string must consist of characters from the Windows 3.x character set. The OpenFile function does not support Unicode file names.
lpOpenBuff
Points to the OFSTRUCT structure that is to receive information about the file when the file is first opened. The structure can be used in subsequent calls to the OpenFile function to refer to the open file.
The OFSTRUCT structure has the following form:
typedef struct _OFSTRUCT { /* of */
BYTE cBytes;
BYTE fFixedDisk;
WORD nErrCode;
WORD Reserved1;
WORD Reserved2;
BYTE szPathName[OFS_MAXPATHNAME];
} OFSTRUCT;
fuMode
Specifies the action to take. These styles can be combined by using the bitwise OR operator:
| Value | Meaning |
| OF_CANCEL | ||
| Ignored. In Win32, the OF_PROMPT style produces a dialog box that contains a Cancel button. | ||
| OF_CREATE | ||
| Creates a new file. If the file already exists, it is truncated to zero length. | ||
| OF_DELETE | ||
| Deletes the file. | ||
| OF_EXIST | ||
| Opens the file, and then closes it. Used to test for file existence. | ||
| OF_PARSE | ||
| Fills the OFSTRUCT data structure but carries out no other action. | ||
| OF_PROMPT | ||
| Displays a dialog box if the requested file does not exist. The dialog box informs the user that Windows cannot find the file, and it contains Retry and Cancel buttons. Pressing the Cancel button directs OpenFile to return a file-not-found error message. | ||
| OF_READ | ||
| Opens the file for reading only. | ||
| OF_READWRITE | ||
| Opens the file for reading and writing. | ||
| OF_REOPEN | ||
| Opens the file using information in the re-open buffer. | ||
| OF_SHARE_COMPAT | ||
| On MS-DOS/Win32, opens the file with compatibility mode, allowing any process on a given machine to open the file any number of times. Other opens with any other sharing mode will fail. On NT/Win32 this flag is mapped to OF_SHARE_DENY_NONE. | ||
| OF_SHARE_DENY_NONE | ||
| Opens the file without denying other processes read or write access to the file. The function fails if the file has been opened in compatibility mode by any other process. | ||
| OF_SHARE_DENY_READ | ||
| Opens the file and denies other processes read access to the file. The function fails if the file has been opened in compatibility mode or for read access by any other process. | ||
| OF_SHARE_DENY_WRITE | ||
| Opens the file and denies other processes write access to the file. The function fails if the file has been opened in compatibility or for write access by any other process. | ||
| OF_SHARE_EXCLUSIVE | ||
| Opens the file with exclusive mode, denying other processes both read and write access to the file. The function fails if the file has been opened in any other mode for read or write access, even by the current process. | ||
| OF_VERIFY | ||
| Verifys that the date and time of the file are the same as when it was previously opened. This is useful as an extra check for read-only files. | ||
| OF_WRITE | ||
| Opens the file for writing only. | ||
The return value specifies an MS-DOS file handle if the function is successful. Otherwise, it is -1, in which case extended error information is available from the GetLastError function.
If the lpszFile parameter specifies a filename and extension only, this function searches for a matching file in the following directories:
1.The current directory.
2.The Windows directory (the directory containing WIN.COM); the GetWindowsDirectory function obtains the pathname of this directory.
3.The Windows system directory (the directory containing such system files as KERNEL.EXE); the GetSystemDirectory function obtains the pathname of this directory.
4.Any of the directories listed in the PATH environment variable.
5.Any directory in the list of directories mapped in a network.
Windows searches the directories in the listed order.
The lpszFile parameter cannot contain wildcard characters.
To close the file after use, the application should call the _lclose function.
CloseHandle, CreateFile, GetSystemDirectory, GetWindowsDirectory,