NotifyCreateFile Event
Fires when a file or directory has been created.
Syntax
public class DefaultCbfilterEventListener implements CbfilterEventListener { ... public void notifyCreateFile(CbfilterNotifyCreateFileEvent e) {} ... } public class CbfilterNotifyCreateFileEvent { public String fileName; public int desiredAccess; public int attributes; public int shareMode; public int options; public int createDisposition; public int status; public int resultCode; }
Remarks
This event fires when the file or directory specified by FileName has been created. Please refer to the File Create/Open Events topic for more information about how the class determines whether to fire this event or NotifyOpenFile.
Applications only need to handle this event if they've added a standard filter rule that includes the FS_NE_CREATE flag. Please note that applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory creation requests.
The DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly-named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE IRP).
DesiredAccess 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.
|
Attributes 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.
|
| 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. |
ShareMode 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.
|
CreateDisposition may contain one of the following values:
| FILE_DISPOSITION_CREATE_NEW | 0x00000001 | Creates a new file, only if it does not already exist.
If the specified file exists, the operation fails with an "already exists" error. |
| FILE_DISPOSITION_CREATE_ALWAYS | 0x00000002 | Creates a new file, always.
If the specified file exists and is writable, the system overwrites the file. If the specified file does not exist and is a valid path, a new file is created. |
| FILE_DISPOSITION_OPEN_EXISTING | 0x00000003 | Opens a file, only if it exists
If the specified file does not exist, opening fails. |
| FILE_DISPOSITION_OPEN_ALWAYS | 0x00000004 | Opens a file, always.
If the specified file exists, the operation succeeds. If the specified file does not exist and is a valid path to a writable location, the a file is created. |
| FILE_DISPOSITION_TRUNCATE_EXISTING | 0x00000005 | Opens a file and truncates it so that its size is zero bytes, only if it exists.
If the specified file does not exist, the operation fails with a "file not found" error. |
Options contains the flags that are described in the CreateOptions parameter of the Native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to Native API. If you need those flags, check both functions' descriptions.
Please refer to Microsoft's documentation for detailed information about these constants.
To determine whether the request was 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;FILE_SYS_ATTR_DIRECTORY will be present if it was specified by the calling process or if the existing filesystem entry is a directory.
To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, like so:
// Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE;Note: files can be deleted in different ways, so don't use this check to take actions related to tracking of file deletion operations. Instead, use the events related to file deletion.
The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method. Please note that this event won't fire for failed requests unless the ProcessFailedRequests property is enabled.
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, set it to a non-zero value to report an appropriate error. Note, however, that this event fires after the operation has already completed, so reporting an error won't actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.
This event is fired asynchronously; please refer to the Event Types topic for more information.