CBFS Connect 2020 Python Edition

Questions / Feedback?

on_create_file Event

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

Syntax

class CBFSCreateFileEventParams(object):
  @property
  def file_name() -> str: ...
  @property
  def desired_access() -> int: ...
  @property
  def attributes() -> int: ...
  @property
  def share_mode() -> int: ...
  @property
  def nt_create_disposition() -> int: ...
  @property
  def nt_desired_access() -> int: ...
  @property
  def file_info() -> int: ...
  @property
  def handle_info() -> int: ...
  @property
  def file_context() -> int: ...
  @file_context.setter
  def file_context(value) -> None: ...
  @property
  def handle_context() -> int: ...
  @handle_context.setter
  def handle_context(value) -> None: ...
  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBFS:
@property
def on_create_file() -> Callable[[CBFSCreateFileEventParams], None]: ...
@on_create_file.setter
def on_create_file(event_hook: Callable[[CBFSCreateFileEventParams], None]) -> None: ...

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 fire_all_open_close_events 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 Windows API's FILE_ATTRIBUTE_DIRECTORY (16, 0x10) constant, like so:

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

If the use_alternate_data_streams 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 route_to_file to have the class route future requests directly to that file. This event's FileInfo value must be passed to route_to_file 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 on_open_file. Normally this won't happen, as the OS already knows which files exist (based on information obtained via on_get_file_info/on_enumerate_directory) 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 on_create_file event; it can either truncate the existing file, or return the ERROR_ALREADY_EXISTS error code via ResultCode.

The DesiredAccess parameter specifies the access mode desired by the process that initiated the request. 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 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.

Please refer to the Windows API's ZwCreateFile function for more 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 route_to_file 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: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

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.

 
 
Copyright (c) 2021 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 Python Edition - Version 20.0 [Build 7880]