CreateFile Event

Fires when the OS wants to create a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void createFile(CbfsCreateFileEvent e) {}
  ...
}

public class CbfsCreateFileEvent {
  public String fileName;
  public int desiredAccess;
  public int attributes;
  public int shareMode;
  public int NTCreateDisposition;
  public int NTDesiredAccess;
  public long fileInfo;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to create a file or directory named FileName using the creation options reflected in Attributes. If the FireAllOpenCloseEvents property is disabled, this event will only fire when the first handle to the specified file or directory is opened. To determine whether the request is for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, like so:

// Check whether the request is for a file or a directory.
bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY;

If the UseAlternateDataStreams property is enabled, this event also fires anytime the OS wants to create a named data stream in a file. Such requests are distinguished by the presence of a colon (:) in the FileName value; the text before the colon is the name of the file itself, and the text after the colon is the name of the stream to create.

To handle this event properly, applications should (at least) perform any actions needed to create and/or open the requested file, directory, or named stream in their backend storage. Applications are also responsible for validating the access rights of the process that initiated the request before performing the requested operation; please refer to the Security Checks topic for more information.

If there's an existing local file that corresponds to the virtual one specified by FileName, the application may call RouteToFile to have the class route future requests directly to that file. This event's FileInfo value must be passed to RouteToFile for request routing to be configured successfully.

In certain cases, a request to open an existing file may unexpectedly be surfaced via this event instead of via OpenFile. Normally this won't happen, as the OS already knows which files exist (based on information obtained via GetFileInfo/EnumerateDirectory) before it sends the create or open request. However, if a file is created externally, a rare condition may occur where said file exists but isn't known to the OS or the virtual filesystem yet. In such cases, the application must decide how to handle the unexpected CreateFile event; it can either truncate the existing file, or return the ERROR_ALREADY_EXISTS error code via ResultCode.

If an original call to CreateFile() or a similar Windows API function included security attributes, the SetFileSecurity event will immediately follow this CreateFile event, and the mentioned security attributes will be passed via SetFileSecurity.

The DesiredAccess parameter specifies the access mode desired by the process that initiated the request; it may contain one or more of the following access flags:


DESIRED_ACCESS_FILE_LIST_DIRECTORY	`0x00000001`	For a directory, the right to list the contents of the directory.
DESIRED_ACCESS_FILE_READ_DATA	`0x00000001`	For a file object, the right to read the corresponding file data. For a directory object, the right to read the corresponding directory data.
DESIRED_ACCESS_FILE_ADD_FILE	`0x00000002`	For a directory, the right to create a file in the directory.
DESIRED_ACCESS_FILE_WRITE_DATA	`0x00000002`	For a file object, the right to write data to the file. For a directory object, the right to create a file in the directory
DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY	`0x00000004`	For a directory, the right to create a subdirectory.
DESIRED_ACCESS_FILE_APPEND_DATA	`0x00000004`	For a file object, the right to append data to the file. (For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).
DESIRED_ACCESS_FILE_READ_EA	`0x00000008`	The right to read extended file attributes.
DESIRED_ACCESS_FILE_WRITE_EA	`0x00000010`	The right to write extended file attributes.
DESIRED_ACCESS_FILE_EXECUTE	`0x00000020`	For a native code file, the right to execute the file. This access right given to scripts may cause the script to be executable, depending on the script interpreter.
DESIRED_ACCESS_FILE_DELETE_CHILD	`0x00000040`	For a directory, the right to delete a directory and all the files it contains, including read-only files.
DESIRED_ACCESS_FILE_READ_ATTRIBUTES	`0x00000080`	The right to read file attributes.
DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES	`0x00000100`	The right to write file attributes.
DESIRED_ACCESS_READ_CONTROL	`0x00020000`	The right to read the information in the file or directory object's security descriptor. This does not include the information in the SACL.
DESIRED_ACCESS_STANDARD_RIGHTS_READ	`0x00020000`	Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor. This does not include the information in the SACL.
DESIRED_ACCESS_STANDARD_RIGHTS_WRITE	`0x00020000`	Same as STANDARD_RIGHTS_READ
DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE	`0x00020000`	Same as STANDARD_RIGHTS_READ
DESIRED_ACCESS_SYNCHRONIZE	`0x00100000`	The right to use the object for synchronization. This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.
DESIRED_ACCESS_FILE_ALL_ACCESS	`0x001F01FF`	All possible access rights for a file.
DESIRED_ACCESS_FILE_GENERIC_READ	`0x00120089`	A combinarion of flags that allow reading of the file. Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.
DESIRED_ACCESS_FILE_GENERIC_WRITE	`0x00120116`	A combinarion of flags that allow modifications to the file. Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.
DESIRED_ACCESS_FILE_GENERIC_EXECUTE	`0x001200A0`	A combinarion of flags that allow execution of the file. Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

This value may differ from the one originally passed to the OS; the class alters it in the following cases:

The DELETE flag is added if the requested CreateDisposition is FILE_SUPERSEDE.
The FILE_WRITE_DATA, FILE_WRITE_EA, and FILE_WRITE_ATTRIBUTES flags are added if the requested CreateDisposition is FILE_OVERWRITE or FILE_OVERWRITE_IF.

The original CreateDisposition and DesiredAccess values are exposed via the NTCreateDisposition and NTDesiredAccess parameters. (Note that these values are in NT format; i.e., as expected by the Windows API's ZwCreateFile function.)

The Attributes parameter contains file attributes; it may contain one or more of the following attributes:


FILE_SYS_ATTR_READ_ONLY	`0x00000001`	The file is read-only. Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.
FILE_SYS_ATTR_HIDDEN	`0x00000002`	The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_SYS_ATTR_SYSTEM	`0x00000004`	A file or directory that the operating system uses a part of, or uses exclusively.
FILE_SYS_ATTR_DIRECTORY	`0x00000010`	The entry is a directory.
FILE_SYS_ATTR_ARCHIVE	`0x00000020`	The entry is an archive file or directory. Applications typically use this attribute to mark files for backup or removal.
FILE_SYS_ATTR_NORMAL	`0x00000080`	A file doesn't have other attributes set. This attribute is only valid when used alone.
FILE_SYS_ATTR_TEMPORARY	`0x00000100`	A file that is being used for temporary storage. File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data is written after the handle is closed.
FILE_SYS_ATTR_SPARSE_FILE	`0x00000200`	A file that is a sparse file.
FILE_SYS_ATTR_REPARSE_POINT	`0x00000400`	A file that is a reparse point or a symbolic link.
FILE_SYS_ATTR_COMPRESSED	`0x00000800`	A file or directory that is compressed. For a file, all of the data in the file is compressed. For a directory, compression is the default for newly created files and subdirectories.
FILE_SYS_ATTR_OFFLINE	`0x00001000`	The data of a file is not available immediately. This attribute indicates that the file data is physically moved to offline storage.
FILE_SYS_ATTR_NOT_CONTENT_INDEXED	`0x00002000`	The file or directory is not to be indexed by the content indexing service.
FILE_SYS_ATTR_ENCRYPTED	`0x00004000`	A file or directory that is encrypted. For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories. Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.
FILE_SYS_ATTR_VIRTUAL	`0x00010000`	Reserved. Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.
FILE_SYS_ATTR_RECALL_ON_OPEN	`0x00040000`	The file or directory has no physical representation on the local system; the item is virtual. Opening the item will be more expensive than normal, e.g. it will cause at least some of it to be fetched from a remote store. This flag is reported by filesystems during directory enumerations.

Attributes specifies both the attributes and create/open options for the new file. Some options, such as FILE_FLAG_SEQUENTIAL_SCAN, FILE_FLAG_WRITE_THROUGH, FILE_FLAG_RANDOM_ACCESS, etc.; may be useful for applications that wish to fine-tune their performance. For example, such information could be used to decide whether it's necessary to locally cache some amount of data that is stored remotely.

The ShareMode parameter specifies the access sharing mode desired by the process that initiated the request; it may contain zero or more of the following share mode flags:


FILE_SYS_SHARE_READ	`0x00000001`	Enables subsequent open operations on a file to request read access. Otherwise, other processes cannot open the file if they request read access. If this flag is not specified, but the file has been opened for read access, file creation or opening fails.
FILE_SYS_SHARE_WRITE	`0x00000002`	Enables subsequent open operations on a file to request write access. Otherwise, other processes cannot open the file if they request write access. If this flag is not specified, but the file has been opened for write access or has a file mapping with write access, file creation or opening fails.
FILE_SYS_SHARE_DELETE	`0x00000004`	Enables subsequent open operations on a file to request delete access. Otherwise, other processes cannot open the file if they request delete access. If this flag is not specified, but the file has been opened for delete access, the function fails. Note: Delete access allows both delete and rename operations.

Please refer to the Windows API's ZwCreateFile function for detailed information about possible values for the DesiredAccess, Attributes, ShareMode, NTCreateDisposition, and NTDesiredAccess parameters.

The FileInfo parameter carries a handle to an object with information about the file. As mentioned above, this value should be used if the application chooses to call the RouteToFile method.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

CBFS Connect 2020 Java Edition

CreateFile Event

Syntax

Remarks