on_get_file_info Event

Fires when the OS needs information about a file or directory.

Syntax

class CBFSGetFileInfoEventParams(object):
  @property
  def file_name() -> str: ...
  @property
  def file_exists() -> bool: ...
  @file_exists.setter
  def file_exists(value) -> None: ...
  @property
  def creation_time() -> datetime.datetime: ...
  @creation_time.setter
  def creation_time(value) -> None: ...
  @property
  def last_access_time() -> datetime.datetime: ...
  @last_access_time.setter
  def last_access_time(value) -> None: ...
  @property
  def last_write_time() -> datetime.datetime: ...
  @last_write_time.setter
  def last_write_time(value) -> None: ...
  @property
  def change_time() -> datetime.datetime: ...
  @change_time.setter
  def change_time(value) -> None: ...
  @property
  def size() -> int: ...
  @size.setter
  def size(value) -> None: ...
  @property
  def allocation_size() -> int: ...
  @allocation_size.setter
  def allocation_size(value) -> None: ...
  @property
  def file_id() -> int: ...
  @file_id.setter
  def file_id(value) -> None: ...
  @property
  def attributes() -> int: ...
  @attributes.setter
  def attributes(value) -> None: ...
  @property
  def hard_link_count() -> int: ...
  @hard_link_count.setter
  def hard_link_count(value) -> None: ...
  @property
  def short_file_name() -> str: ...
  @short_file_name.setter
  def short_file_name(value) -> None: ...
  @property
  def real_file_name() -> str: ...
  @real_file_name.setter
  def real_file_name(value) -> None: ...
  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

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

Remarks

This event fires when the OS needs information about the file or directory specified by FileName and in some other cases (see the notes below).

To handle this event properly, applications should first check whether the specified file or directory exists, and set FileExists accordingly. If no such file or directory exists, set FileExists to False. If the file or directory exists, set FileExists to True and supply its information using the following parameters:

• CreationTime, LastAccessTime, LastWriteTime, ChangeTime: Set to the corresponding time values of the file or directory, specified in UTC. Any non-applicable time values can be left unchanged, or set to January 1, 1970 00:00:00 UTC.
  • Leave LastAccessTime unchanged if the support_last_access_time_attribute property is disabled.
  • Leave ChangeTime unchanged if the support_change_time_attribute property is disabled.
• Size: For files, set to the size of the file, in bytes; for directories, set to 0.
• AllocationSize: For files, set to the number of bytes allocated locally for the file; for directories, set to 0. The allocation size is typically a multiple of the ClusterSize.
• FileId: Set to the unique Id of the file or directory. Please refer to the File IDs topic for more information.
• Attributes: Set to the attributes of the file or directory.
• HardLinkCount: If the use_hard_links property is enabled, set to the number of hard links that point to the file. The default value is 1 (which is also the only valid value for directories). Please refer to the Hard Links topic for more information.
• ShortFileName: If the use_short_file_names property is enabled, set to the short (8.3) name of the file.
  • If use_short_file_names is enabled, it's possible that FileName is already a short name. In such cases, return the same name in ShortFileName.
  • The short name must adhere to the 8.3 name format; please refer to the Short File Names topic for more information.
• RealFileName: If the use_case_sensitive_file_names property is enabled, and FileName's casing differs from that of the actual file or directory name, set to the "real" name of said file or directory.
  • For example, if the requested FileName is QWERTY.txt, but the only similarly-named file in the virtual filesystem is qwErTy.TxT, then this parameter should be set to the latter.
  • If the specified FileName includes a path, it must be preserved in the value returned via RealFileName; only the casing of the filename and extension may be corrected.
  • The length of the returned name (and path, if applicable) must not exceed the value of the max_file_path_length property.

Notes:

1. if the use_case_sensitive_file_names and use_alternate_data_streams properties are both enabled, this event may also be used to obtain the "real name" of a named stream. When returning the name of a named stream via the RealFileName parameter, prepend a colon (:) to the stream's name so that it looks like, e.g, :Zone.Identifier.
2. if the UpdateFileMetadataOnOpen config setting is True, this event will fire right after the on_open_file event but only if the file was fully closed before on_open_file.

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.