CBFS Connect 2020 Python Edition

Questions / Feedback?

on_enumerate_directory Event

Fires when the OS wants to enumerate a directory's contents.

Syntax

class CBFSEnumerateDirectoryEventParams(object):
  @property
  def directory_name() -> str: ...
  @property
  def mask() -> str: ...
  @property
  def case_sensitive() -> bool: ...
  @property
  def restart() -> bool: ...
  @property
  def file_found() -> bool: ...
  @file_found.setter
  def file_found(value) -> None: ...
  @property
  def file_name() -> str: ...
  @file_name.setter
  def file_name(value) -> None: ...
  @property
  def short_file_name() -> str: ...
  @short_file_name.setter
  def short_file_name(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 reparse_tag() -> int: ...
  @reparse_tag.setter
  def reparse_tag(value) -> None: ...
  @property
  def handle_info() -> int: ...
  @property
  def directory_context() -> int: ...
  @directory_context.setter
  def directory_context(value) -> None: ...
  @property
  def handle_context() -> int: ...
  @handle_context.setter
  def handle_context(value) -> None: ...
  @property
  def enumeration_context() -> int: ...
  @enumeration_context.setter
  def enumeration_context(value) -> None: ...
  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

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

Remarks

This event fires when the OS wants to enumerate the contents of the directory specified by DirectoryName (which will have been opened via on_open_file).

To handle this event properly, applications must return information about each directory entry (file, subdirectory, link) that matches the specified Mask. For each matching entry found, set FileFound to True and supply the entry's information using the following parameters:

  • FileName: Set to the name of the entry (not including its path).
  • ShortFileName: If the use_short_file_names property is enabled, set to the short (8.3) name of the entry.
    • The short name must adhere to the 8.3 name format; please refer to the Short File Names topic for more information.
  • CreationTime, LastAccessTime, LastWriteTime, ChangeTime: Set to the entry's corresponding time values, specified in UTC. Any time values not applicable to the entry can be left unchanged, or set to January 1, 1970 00:00:00 UTC.
  • Size: For file entries, set to the size of the file, in bytes; for other entries, set to 0.
  • AllocationSize: For file entries, set to the number of bytes allocated locally for the file; for other entries, set to 0. The allocation size is typically a multiple of the ClusterSize.
  • FileId: Set to the unique Id of the file or directory represented by the entry. Please refer to the File IDs topic for more information.
  • Attributes: Set to the file or directory attributes of the entry.
  • ReparseTag: If the use_reparse_points property is enabled, and the entry is a reparse point, set to the reparse point's tag.
    • Also, be sure that the FILE_ATTRIBUTE_REPARSE_POINT attribute is included in the value supplied for the Attributes parameter.
    • The tag should have been stored when the reparse point was created (i.e., during an earlier on_set_reparse_point event).
    • Please refer to the Reparse Points topic for more information.

If there are no more matching entries present, set FileFound to False and leave the above parameters unchanged. When the OS is finished with the directory enumeration, the on_close_directory_enumeration event will fire.

The Mask parameter specifies the filename mask that should be used to filter the results. This value may contain any combination of valid filename characters and wildcards (the * and ? characters). Alternatively, it may be an exact filename (i.e., a value without any wildcards), as some applications query file information by specifying an exact filename in an enumeration.

The CaseSensitive parameter indicates whether entry names should be matched against the specified Mask in a case-sensitive manner. It will always be False if the use_case_sensitive_file_names property is disabled. (Note: This parameter is not currently used; the search is always case-insensitive.)

The Restart parameter, if True, indicates that the enumeration should be restarted from the beginning of the directory. Any previously-reported entries that still exist should be reported again.

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 DirectoryContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the directory, specific handle, and enumeration; respectively. (For general-purpose events, the DirectoryContext is called FileContext instead.) DirectoryContext corresponds to the FileContext in the file/directory creation, opening, and closing events. 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]