CreateFile (Compact 2013)
This function creates, opens, or truncates a file, COM port, device, service, or console, and returns a handle to access the object.
HANDLE CreateFile( LPCTSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES lpSecurityAttributes, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes, HANDLE hTemplateFile );
[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, the default string size limit is MAX_PATH characters. This limit is related to how this function parses paths.
When lpFileName points to a COM port to open, include a colon after the name. When using IrCOMM, specify COM3:.
[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.
Specifies execute access only.
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.
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.
[in] Share mode for the object. If this parameter is set to zero, the object cannot be shared. Subsequent open operations on the object fail until the handle is closed.
This parameter can be set to one or more of the values shown in the following table.
Indicates that subsequent open operations on the object succeed only if read access is requested.
Indicates that subsequent open operations on the object succeed only if write access is requested.
[in] Not used.
[in] Action to take on files that exist, and which action to take when files do not exist. The following table shows possible values.
Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes.
Opens the file. The function fails if the file does not exist.
Creates a new file. The function fails if the specified file already exists.
Opens the file, if it exists. If the file does not exist, the function creates the file as if this parameter were set to CREATE_NEW.
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.
[in] File attributes and flags for the file.
Any combination of permitted attributes is acceptable for this parameter. All other file attributes override the FILE_ATTRIBUTE_NORMAL value. The following table shows possible attribute values.
Indicates that the file is archived. Applications use this attribute to mark files for backup or removal.
Indicates that the file or directory is compressed. For a file, this means that all data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
Indicates that the file is hidden. It is not to be included in an ordinary directory listing.
Indicates that the file has no other attributes set. This attribute is valid only if used alone.
Indicates that the file is read-only.
Indicates that the file is a DLL module that has an implicit reference from at least one other file that is in the modules section of the image. A file with this attribute set cannot replace the functionality of the DLL with a RAM copy of the same DLL.
Indicates that the file is part of or is used exclusively by the OS.
The following table shows possible flag values.
Indicates that the CreateFile operation is to get a handle to the file directory.
Indicates that the file is opened with no system caching. This does not affect disk caching.
This flag is not supported. However, multiple read/write operations pending on a device at a time are supported.
Indicates that the file is accessed randomly. The system can use this as a hint to optimize file caching.
Instructs the system to write through any intermediate cache and go directly to disk.
[in] Ignored; as a result, this function does not copy the extended attributes to the new file.
An open handle to the specified file indicates success. If the specified file exists before the function call and dwCreationDisposition is set to 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.
Use the CloseHandle function to close an object handle returned by this function.
This function 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 this function are those in the FILES section.
If the FILE_FLAG_NO_BUFFERING flag is set, the system opens a file with no system caching. This flag does not affect hard disk caching. When combined with FILE_FLAG_OVERLAPPED, the flag gives maximum asynchronous performance because the I/O does not rely on the synchronous operations of the memory manager. However, some I/O operations take more time because data is not being held in the cache. In addition, the file metadata may still be cached. To flush the metadata to disk, use the FlushFileBuffers function.
An application must meet certain requirements when working with files that are opened with FILE_FLAG_NO_BUFFERING:
File access must begin at byte offsets within a file that are integer multiples of the volume sector size.
File access must be for numbers of bytes that are integer multiples of the volume sector size. For example, if the sector size is 512 bytes, an application can request reads and writes of 512, 1024, 1536, or 2048 bytes, but not of 335, 981, or 7171 bytes.
Buffer addresses for read and write operations may have to be sector-aligned, which means aligned on addresses in memory that are integer multiples of the volume sector size. Depending on the disk, this requirement may not be enforced.
One way to align buffers on integer multiples of the volume sector size is to use the VirtualAlloc function to allocate buffers. VirtualAlloc allocates memory that is aligned on addresses that are integer multiples of OS memory page size. Because both memory page and volume sector sizes are powers of 2, this memory is also aligned on addresses that are integer multiples of a volume sector size. Memory pages are 4 to 8 KB in size. Sectors are 512 bytes (hard disk) or 2048 bytes (CD). Therefore, volume sectors can never be larger than memory pages.
The HKEY_LOCAL_MACHINE\System\StorageManager\FATFS\DirHandleWrite registry value must be set to 1 in order to get a writable handle to the file directory when using the FILE_FLAG_BACKUP_SEMANTICS flag. This registry setting is not required to get a read-only handle to the file directory. For more information about editing the registry, see Registry Settings for FATFS Disk Caching.
An application can check the volume sector size by calling the GetDiskFreeSpaceEx function.