 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This function creates, opens, or truncates a file, communications resource, disk device, or console. It returns a handle that can be used to access the object. It can also open and return a handle to a directory.
A remote application interface (RAPI) version of this function exists, and it is named CeCreateFile.
HANDLE CreateFile( LPCTSTR lpFileName , DWORD dwDesiredAccess , DWORD dwShareMode , LPSECURITY_ATTRIBUTES lpSecurityAttributes , DWORD dwCreationDispostion , DWORD dwFlagsAndAttributes , HANDLE hTemplateFile );
Parameters
- lpFileName
- [in] Pointer to a null-terminated string that specifies the
name of the object (file, communications resource, disk device,
console, or directory) to create or open.
If * lpFileNameis a path, there is a default string size limit of MAX_PATH characters. This limit is related to how the CreateFilefunction parses paths.
When lpFileNamepoints to a communications resource to open, you must include a colon after the name. For example, specify "COM1: " to open that port. When using IrCOMM, specify "COM3:".
- dwDesiredAccess
- [in] Specifies the type of access to the object. An application
can obtain read access, write access, read-write access, or device
query access. This parameter can be any combination of the
following values.
Value Description 0 Specifies device query access to the object. An application can query device attributes without accessing the device. GENERIC_READ Specifies read access to the object. Data can be read from the file and the file pointer can be moved. Combine with GENERIC_WRITE for read-write access. GENERIC_WRITE Specifies write access to the object. Data can be written to the file and the file pointer can be moved. Combine with GENERIC_READ for read-write access. - dwShareMode
- [in] Specifies how the object can be shared. If
dwShareModeis 0, the object cannot be shared. Subsequent
open operations on the object will fail, until the handle is
closed.
To share the object, use a combination of one or more of the following values:
Value Description FILE_SHARE_READ Subsequent open operations on the object will succeed only if read access is requested. FILE_SHARE_WRITE Subsequent open operations on the object will succeed only if write access is requested. - lpSecurityAttributes
- [in] Ignored; set to NULL.
- dwCreationDispostion
- [in] Specifies which action to take on files that exist, and
which action to take when files do not exist. For more information
about this parameter, see the Remarks section. This parameter must
be one of the following values:
Value Description CREATE_NEW Creates a new file. The function fails if the specified file already exists. CREATE_ALWAYS Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes. OPEN_EXISTING Opens the file. The function fails if the file does not exist. See the Remarks section for a discussion of why you should use the OPEN_EXISTING flag if you are using the CreateFilefunction for devices, including the console. OPEN_ALWAYS Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreationDispositionwere CREATE_NEW. TRUNCATE_EXISTING Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist. - dwFlagsAndAttributes
- [in] Specifies the file attributes and flags for the file.
Any combination of the following attributes is acceptable for the dwFlagsAndAttributesparameter, except all other file attributes override FILE_ATTRIBUTE_NORMAL.
Value Description FILE_ATTRIBUTE_ARCHIVE The file should be archived. Applications use this attribute to mark files for backup or removal. FILE_ATTRIBUTE_HIDDEN The file is hidden. It is not to be included in an ordinary directory listing. FILE_ATTRIBUTE_NORMAL The file has no other attributes set. This attribute is valid only if used alone. FILE_ATTRIBUTE_READONLY The file is read only. Applications can read the file but cannot write to it or delete it. FILE_ATTRIBUTE_SYSTEM The file is part of or is used exclusively by the operating system. FILE_ATTRIBUTE_TEMPORARY Not supported. Any combination of the following flags is acceptable for the dwFlagsAndAttributesparameter.
Value Description FILE_FLAG_WRITE_THROUGH Instructs the system to write through any intermediate cache and go directly to disk. The system can still cache write operations, but cannot lazily flush them. FILE_FLAG_OVERLAPPED This flag is not supported; however, multiple reads/writes pending on a device at a time are allowed. FILE_FLAG_RANDOM_ACCESS Indicates that the file is accessed randomly. The system can use this as a hint to optimize file caching. - hTemplateFile
- [in] Ignored; as a result,
CreateFiledoes not copy the extended attributes to the new
file.
Return Values
An open handle to the specified file indicates success. If the specified file exists before the function call and dwCreationDispositionis CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastErrorreturns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file does not exist before the call, GetLastErrorreturns zero. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.
For Windows CE versions 1.0 through 2.01, an application cannot use GetLastErrorto determine whether a file existed before the call to CreateFile.
Remarks
Use the CloseHandlefunction to close an object handle returned by CreateFile.
As noted above, specifying zero for dwDesiredAccessallows an application to query device attributes without actually accessing the device. This type of querying is useful, for example, if an application wants to determine the size of a floppy disk drive and the formats it supports without having a floppy in the drive.
Files
When creating a new file, the CreateFilefunction performs the following actions:
- Combines the file attributes and flags specified by dwFlagsAndAttributeswith FILE_ATTRIBUTE_ARCHIVE.
- Sets the file length to zero.
When opening an existing file, CreateFileignores the file attributes specified by dwFlagsAndAttributesand sets the file length according to the value of dwCreationDisposition.
To store the maximum number of files on PC Card storage devices, limit file names to eight uppercase characters and file extensions to three uppercase characters. Also, do not allow non-OEM characters in file names. File names that do not conform to these limits require more than one physical directory entry on a PC Card.
Communications Resources
The CreateFilefunction can create a handle to a communications resource. By setting the dwCreationDispositionparameter to OPEN_EXISTING, read, write, or read-write access can be specified.
Directories
An application cannot create a directory with CreateFile; it must call CreateDirectoryto create a directory.
Some file systems, such as NTFS, support compression or encryption for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression and encryption attributes of its parent directory.
Requirements
Runs on Versions Defined in Include Link to Windows CE OS 1.0 and later Winbase.h Coredll.lib Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
CeCreateFile, CloseHandle, CreateDirectory, GetLastError, ReadFile, VirtualAlloc