CREATEFILE2_EXTENDED_PARAMETERS structure (fileapi.h)
Contains optional extended parameters for CreateFile2.
Syntax
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
Members
dwSize
Contains the size of this structure, sizeof(CREATEFILE2_EXTENDED_PARAMETERS).
dwFileAttributes
The file or device attributes and flags, FILE_ATTRIBUTE_NORMAL being the most common default value for files.
This parameter can include any combination of the available file attributes (FILE_ATTRIBUTE_*). All other file attributes override FILE_ATTRIBUTE_NORMAL.
Note
When CreateFile2 opens an existing file, it generally combines the file flags with the file attributes of the existing file, and ignores any file attributes supplied as part of dwFlagsAndAttributes. Special cases are detailed in Creating and Opening Files.
Some of the following file attributes and flags may only apply to files and not necessarily all other types of devices that CreateFile2 can open. For additional information, see the Remarks section of the CreateFile2 reference page and Creating and Opening Files.
For more advanced access to file attributes, see SetFileAttributes. For a complete list of all file attributes with their values and descriptions, see File Attribute Constants.
| Attribute | Meaning |
|---|---|
|
The file should be archived. Applications use this attribute to mark files for backup or removal. |
|
The file or directory is encrypted. For a file, this means that all data in the file is encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories. For more information, see File Encryption.
This flag has no effect if FILE_ATTRIBUTE_SYSTEM is also specified. This flag is not supported on Home, Home Premium, Starter, or ARM editions of Windows. This flag is not supported when called from a Windows Store app. |
|
The file is hidden. Do not include it in an ordinary directory listing. |
|
A file or directory that is configured with integrity. For a file, all data streams in the file have integrity. For a directory, integrity is the default for newly created files and subdirectories, unless the caller specifies otherwise.
This flag is only supported on the ReFS file system. |
|
The file does not have other attributes set. This attribute is valid only if used alone. |
|
The data of a file is not immediately available. This attribute indicates that file data is physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software. Applications should not arbitrarily change this attribute. |
|
The file is read only. Applications can read the file, but cannot write to or delete it. |
|
The file is part of or used exclusively by an operating system. |
|
The file is being used for temporary storage.
For more information, see the Caching Behavior section of this topic. |
dwFileFlags
This parameter can contain combinations of flags (FILE_FLAG_*) for control of file or device caching behavior, access modes, and other special-purpose flags.
| Flag | Meaning |
|---|---|
|
The file is being opened or created for a backup or restore operation. The system ensures that the calling process overrides file security checks when the process has SE_BACKUP_NAME and SE_RESTORE_NAME privileges. For more information, see Changing Privileges in a Token.
You must set this flag to obtain a handle to a directory. A directory handle can be passed to some functions instead of a file handle. For more information, see the Remarks section. |
|
The file is to be deleted immediately after all of its handles are closed, which includes the specified handle and any other open or duplicated handles.
If there are existing open handles to a file, the call fails unless they were all opened with the FILE_SHARE_DELETE share mode. Subsequent open requests for the file fail, unless the FILE_SHARE_DELETE share mode is specified. |
|
A device map is a mapping between DOS device names and devices in the system, and is used when resolving DOS names. Separate device maps exists for each user in the system, and users can manage their own device maps. Typically during impersonation, the impersonated user's device map would be used. However, when this flag is set, the process user's device map is used instead. |
|
The file or device is being opened with no system caching for data reads and writes. This flag does not affect hard disk caching or memory mapped files.
There are strict requirements for successfully working with files opened with CreateFile2 using the FILE_FLAG_NO_BUFFERING flag, for details see File Buffering. |
|
The file data is requested, but it should continue to be located in remote storage. It should not be transported back to local storage. This flag is for use by remote storage systems. |
|
Normal reparse point processing will not occur; CreateFile2 will attempt to open the reparse point. When a file is opened, a file handle is returned, whether or not the filter that controls the reparse point is operational.
This flag cannot be used with the CREATE_ALWAYS flag. If the file is not a reparse point, then this flag is ignored. For more information, see the Remarks section. |
|
The file is being opened and an opportunistic lock (oplock) on the file is being requested as a single atomic operation. The file system checks for oplocks before it performs the create operation, and will fail the create with a last error code of ERROR_CANNOT_BREAK_OPLOCK if the result would be to break an existing oplock.
If you use this flag and your call to the CreateFile2 function successfully returns, the first operation you should perform on the file handle is to request an oplock by calling the DeviceIOControl function and then pass in FSCTL_REQUEST_OPLOCK or one of the other Opportunistic Lock Operations. If you perform other file system operations with the file handle before requesting an oplock, a deadlock might occur. Note You can safely call the CloseHandle function on the file handle without first requesting an oplock.
|
|
The file or device is being opened or created for asynchronous I/O.
When subsequent I/O operations are completed on this handle, the event specified in the OVERLAPPED structure will be set to the signaled state. If this flag is specified, the file can be used for simultaneous read and write operations. If this flag is not specified, then I/O operations are serialized, even if the calls to the read and write functions specify an OVERLAPPED structure. For information about considerations when using a file handle created with this flag, see the Synchronous and Asynchronous I/O Handles section of this topic. |
|
Access will occur according to POSIX rules. This includes allowing multiple files with names, differing only in case, for file systems that support that naming. Use care when using this option, because files created with this flag may not be accessible by applications that are written for MS-DOS or 16-bit Windows. |
|
Access is intended to be random. The system can use this as a hint to optimize file caching.
This flag has no effect if the file system does not support cached I/O and FILE_FLAG_NO_BUFFERING. For more information, see the Caching Behavior section of this topic. |
|
The file or device is being opened with session awareness. If this flag is not specified, then per-session devices (such as a device using RemoteFX USB Redirection) cannot be opened by processes running in session 0. This flag has no effect for callers not in session 0. This flag is supported only on server editions of Windows.
Windows Server 2008 R2 and Windows Server 2008: This flag is not supported before Windows Server 2012. |
|
Access is intended to be sequential from beginning to end. The system can use this as a hint to optimize file caching.
This flag should not be used if read-behind (that is, backwards scans) will be used. This flag has no effect if the file system does not support cached I/O and FILE_FLAG_NO_BUFFERING. For more information, see the Caching Behavior section of this topic. |
|
Write operations will not go through any intermediate cache, they will go directly to disk.
For additional information, see the Caching Behavior section of this topic. |
dwSecurityQosFlags
The dwSecurityQosFlags parameter specifies SQOS information. For more information, see Impersonation Levels.
lpSecurityAttributes
A pointer to a SECURITY_ATTRIBUTES structure that contains two separate but related data members: an optional security descriptor, and a Boolean value that determines whether the returned handle can be inherited by child processes.
This parameter can be NULL.
If this parameter is NULL, the handle returned by CreateFile2 cannot be inherited by any child processes the application may create and the file or device associated with the returned handle gets a default security descriptor.
The lpSecurityDescriptor member of the structure specifies a SECURITY_DESCRIPTOR for a file or device. If this member is NULL, the file or device associated with the returned handle is assigned a default security descriptor.
CreateFile2 ignores the lpSecurityDescriptor member when opening an existing file or device, but continues to use the bInheritHandle member.
The bInheritHandle member of the structure specifies whether the returned handle can be inherited.
For more information, see the Remarks section of the CreateFile2 topic.
hTemplateFile
A valid handle to a template file with the GENERIC_READ access right. The template file supplies file attributes and extended attributes for the file that is being created.
This parameter can be NULL.
When opening an existing file, CreateFile2 ignores this parameter.
When opening a new encrypted file, the file inherits the discretionary access control list from its parent directory. For additional information, see File Encryption.
Remarks
To compile an application that uses the CREATEFILE2_EXTENDED_PARAMETERS structure, define the _WIN32_WINNT macro as 0x0602 or later. For more information, see Using the Windows Headers.
Caching Behavior
Several of the possible values for the dwFileFlags member are used to control or affect how the data associated with the handle is cached by the system. They are:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
If none of these flags is specified, the system uses a default general-purpose caching scheme. Otherwise, the system caching behaves as specified for each flag.
Some of these flags should not be combined. For instance, combining FILE_FLAG_RANDOM_ACCESS with FILE_FLAG_SEQUENTIAL_SCAN is self-defeating.
Specifying the FILE_FLAG_SEQUENTIAL_SCAN flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip forward over small ranges of bytes. If an application moves the file pointer for random access, optimum caching performance most likely will not occur. However, correct operation is still guaranteed.
The flags FILE_FLAG_WRITE_THROUGH and FILE_FLAG_NO_BUFFERING are independent and may be combined.
If FILE_FLAG_WRITE_THROUGH is used but FILE_FLAG_NO_BUFFERING is not also specified, so that system caching is in effect, then the data is written to the system cache but is flushed to disk without delay.
If FILE_FLAG_WRITE_THROUGH and FILE_FLAG_NO_BUFFERING are both specified, so that system caching is not in effect, then the data is immediately flushed to disk without going through the Windows system cache. The operating system also requests a write-through of the hard disk's local hardware cache to persistent media.
Note
Not all hard disk hardware supports this write-through capability.
Proper use of the FILE_FLAG_NO_BUFFERING flag requires special application considerations. For more information, see File Buffering.
A write-through request via FILE_FLAG_WRITE_THROUGH also causes NTFS to flush any metadata changes, such as a time stamp update or a rename operation, that result from processing the request. For this reason, the FILE_FLAG_WRITE_THROUGH flag is often used with the FILE_FLAG_NO_BUFFERING flag as a replacement for calling the FlushFileBuffers function after each write, which can cause unnecessary performance penalties. Using these flags together avoids those penalties. For general information about the caching of files and metadata, see File Caching.
When FILE_FLAG_NO_BUFFERING is combined with FILE_FLAG_OVERLAPPED, the flags give 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. Also, the file metadata may still be cached (for example, when creating an empty file). To ensure that the metadata is flushed to disk, use the FlushFileBuffers function.
Specifying the FILE_ATTRIBUTE_TEMPORARY attribute causes file systems to avoid writing data back to mass storage if sufficient cache memory is available, because an application deletes a temporary file after a handle is closed. In that case, the system can entirely avoid writing the data. Although it does not directly control data caching in the same way as the previously mentioned flags, the FILE_ATTRIBUTE_TEMPORARY attribute does tell the system to hold as much as possible in the system cache without writing and therefore may be of concern for certain applications.
Synchronous and Asynchronous I/O Handles
CreateFile2 provides for creating a file or device handle that is either synchronous or asynchronous. A synchronous handle behaves such that I/O function calls using that handle are blocked until they complete, while an asynchronous file handle makes it possible for the system to return immediately from I/O function calls, whether they completed the I/O operation or not. As stated previously, this synchronous versus asynchronous behavior is determined by specifying FILE_FLAG_OVERLAPPED within the dwFileFlags member of the CREATEFILE2_EXTENDED_PARAMETERS structure passed in the pCreateExParams parameter. There are several complexities and potential pitfalls when using asynchronous I/O; for more information, see Synchronous and Asynchronous I/O.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2012 [desktop apps | UWP apps] |
| Header | fileapi.h (include Windows.h) |