CreateFile (Windows CE 5.0)

Windows CE 5.0
Send Feedback

This function creates, opens, or truncates a file, COM port, device, service, or console. It returns a handle that you can use to access the object.

A RAPI version of this function exists, and it is named CeCreateFile (RAPI).

HANDLE CreateFile(
  LPCTSTR lpFileName, 
  DWORD dwDesiredAccess, 
  DWORD dwShareMode, 
  LPSECURITY_ATTRIBUTES lpSecurityAttributes, 
  DWORD dwCreationDisposition, 
  DWORD dwFlagsAndAttributes, 
  HANDLE hTemplateFile
); 

Parameters

lpFileName
[in] Pointer to a null-terminated string that specifies the name of the object, such as file, COM port, disk device, or console, to create or open.

If *lpFileName is a path, there is a default string size limit of MAX_PATH characters. This limit is related to how the CreateFile function parses paths.

When lpFileName points to a COM port 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] Type of access to the object. An application can obtain read-only access, write-only access, read/write access, or device query access. The following table shows possible values for dwDesiredAccess.
ValueDescription
0Specifies device query access to the object. An application can query device attributes without accessing the device.
GENERIC_READSpecifies 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_WRITESpecifies 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] Share mode for object. If dwShareMode is zero, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed.

This parameter can be set to one or more values. The following table shows the possible values for dwShareMode.

ValueDescription
FILE_SHARE_READIndicates that subsequent open operations on the object will succeed only if read access is requested.
FILE_SHARE_WRITEIndicates that subsequent open operations on the object will succeed only if write access is requested.
lpSecurityAttributes
[in] Ignored; set to NULL.
dwCreationDisposition
[in] Action to take on files that exist, and which action to take when files do not exist. For more information on this parameter, see Remarks. The following table shows possible values for dwCreationDisposition.
ValueDescription
CREATE_NEWCreates a new file. The function fails if the specified file already exists.
CREATE_ALWAYSCreates a new file. If the file exists, the function overwrites the file and clears the existing attributes.
OPEN_EXISTINGOpens the file. The function fails if the file does not exist.

For an explanation why you should use the OPEN_EXISTING flag if you are using the CreateFile function for devices, including the console, see Remarks.

OPEN_ALWAYSOpens the file, if it exists. If the file does not exist, the function creates the file as if dwCreationDisposition were CREATE_NEW.
TRUNCATE_EXISTINGOpens 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] File attributes and flags for the file.

Any combination of permitted attributes is acceptable for the dwFlagsAndAttributes parameter. All other file attributes override FILE_ATTRIBUTE_NORMAL. The following table shows possible attribute values for dwFlagsAndAttributes.

ValueDescription
FILE_ATTRIBUTE_ARCHIVEIndicates that the file should be archived. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSEDIndicates that the file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_HIDDENIndicates that the file is hidden. It is not to be included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMALIndicates that the file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_READONLYIndicates that the file is read-only.
FILE_ATTRIBUTE_SYSTEMIndicates that the file is part of or is used exclusively by the operating system (OS).
FILE_ATTRIBUTE_ROMMODULEIndicates that the file is a dynamic-link library (DLL) module that has an implicit reference from at least one other file that is in the modules section of the image. A file having this attribute cannot replace the functionality of the DLL with a RAM copy of the same DLL.
FILE_ATTRIBUTE_TEMPORARYNot supported.

Any combination of permitted flags is acceptable for the dwFlagsAndAttributes parameter. The following table shows permitted flag values for dwFlagsAndAttributes.

ValueDescription
FILE_FLAG_WRITE_THROUGHInstructs 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_OVERLAPPEDThis flag is not supported; however, multiple read/write operations pending on a device at a time are allowed.
FILE_FLAG_RANDOM_ACCESSIndicates that the file is accessed randomly. The system can use this as a hint to optimize file caching.
hTemplateFile
[in] Ignored; as a result, CreateFile does 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 dwCreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file does not exist before the call, GetLastError returns zero. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

For Windows CE 2.01 and earlier, an application cannot use GetLastError to determine whether a file existed before the call to CreateFile.

Remarks

Use the CloseHandle function to close an object handle returned by CreateFile.

As noted previously, specifying zero for dwDesiredAccess allows 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 disk drive and the formats it supports without having a disk in the drive.

The following list shows how CreateFile operates on files, communication resources, devices, services, and consoles:

  • Files

    When creating a new file or truncating an existing file, the CreateFile function performs the following actions:

    • Combines the file attributes and flags specified by dwFlagsAndAttributes with FILE_ATTRIBUTE_ARCHIVE.
    • Sets the file length to zero.
    • CreateFile cannot be used to access files in the MODULES section of ROM. Modules are stored in a different format that applications cannot access. The only ROM files that can be accessed using CreateFile are those in the FILES section.

    When opening an existing file, CreateFile ignores the file attributes specified by dwFlagsAndAttributes and 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.

    Using the FILE_FLAG_RANDOM_ACCESS flag in the RAM file system, which places files in the object store, will prevent a file from being compressed. If performance is an issue, this could be the correct solution. Read and write operations to a compressed file are slower than read and write operations to an uncompressed file.

The OS does not support the concept of a current directory. If a path to a file is not supplied along with the file name, the OS will look for the file in the \Windows directory as well as in the root of the file system. To access a file in any other path, the application must supply the absolute path to the file. In some cases, the GetModuleFileName function can supply the working directory of the currently running executable file.

  • COM ports

    The CreateFile function can create a handle to a COM port. By setting the dwCreationDisposition parameter to OPEN_EXISTING, read-only, write-only, or read/write access can be specified.

  • Devices

    Volume handles may be opened as noncached at the discretion of the file system, even when the noncached option is not specified with CreateFile. You should assume that all Microsoft file systems open volume handles as noncached. The restrictions on noncached I/O for files also apply to volumes.

    A file system may or may not require buffer alignment even though the data is noncached. However, if the noncached option is specified when opening a volume, buffer alignment is enforced regardless of the file system on the volume. Microsoft recommends that all file systems open volume handles as noncached and follow the noncached I/O restrictions.

    CreateFile should only be used on a trusted $bus handle. For more information, see Device Manager Security.

    You can use the CreateFile function to open a disk drive or a partition on a disk drive. The function returns a handle to the disk device. That handle can be used with the DeviceIoControl function. The following list shows the requirements that must be met for such a call to succeed:

    • The caller must have administrative privileges for the operation to succeed on a hard disk drive.
    • The lpFileName string should be of the form DSKx: to open the hard disk x. Hard disk numbers start at one. For example, DSK2: obtains a handle to the second physical drive on the user's computer.
    • The dwCreationDisposition parameter must have the OPEN_EXISTING value.
    • When opening a disk or a partition on a hard disk, you must set the FILE_SHARE_WRITE flag in the dwShareMode parameter.
  • Services

    For information on using CreateFile with services, see Services.exe.

  • Consoles

    If Console.dll is present in the OS image, an application can use the direct console name, CONn:, to open the console with CreateFile, if it has been previously registered. n is a number between zero and 9.

  • Directories

    An application cannot create a directory with CreateFile; it must call CreateDirectory.

Windows Mobile Remarks

You should not access files with the attribute FILE_ATTRIBUTE_ROMMODULE as normal files. Although the CreateFile function will succeed on these files, reading the contents or accessing the contents of the file through file mapping will return unexpected data.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Winbase.h.
Link Library: Coredll.lib.

See Also

Services.exe | CeCreateFile (RAPI) | CloseHandle | CreateDirectory | ReadFile


Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.


Show: