on_find_first Event

This event signifies the start of the custom file listing retrieval mechanism.

Syntax

class SFTPServerFindFirstEventParams(object):
  @property
  def connection_id() -> int: ...
  @property
  def path() -> str: ...
  @property
  def operation_status() -> int: ...
  @operation_status.setter
  def operation_status(value) -> None: ...
  @property
  def handle() -> str: ...
  @handle.setter
  def handle(value) -> None: ...

# In class SFTPServer:
@property
def on_find_first() -> Callable[[SFTPServerFindFirstEventParams], None]: ...
@on_find_first.setter
def on_find_first(event_hook: Callable[[SFTPServerFindFirstEventParams], None]) -> None: ...

Remarks

on_find_first, on_find_next, and on_find_close events represent a mechanism for providing customized file listings to class. They are only fired if Action parameter of the preceding on_before_find event was set to fraCustom.

The behaviour of these events mimics that of the standard FindFirst/FindNext/FindClose functions found in many operating systems/frameworks. on_find_first fires once to request the first list entry; on_find_next then fires continuously in a loop to request all subsequent entries. To indicate that the listing is over, set OperationStatus parameter to ostEOF. Not doing so may lead to an endless loop and session freeze, as the component would continue firing on_find_next infinitely waiting for the EOF marker.

The handlers for both on_find_first and on_find_next events should be implemented in the following way: if there are more entries in the directory to pass back to the server component,

• set OperationStatus to ostOK,
• fill in client_file_entry with the details of the next entry,
• commit the entry to the server using set_client_file_entry method.

When all the entries from the requested directory have been passed to the server component, set OperationStatus to ostEOF. The server will then fire on_find_close event to notify your code that the file listing is completed.

Use the by-ref Handle parameter to assign a handle (a unique identifier) to the file listing procedure inside the on_find_first event handler. This identifier will then be passed to all subsequent on_find_next and on_find_close calls to let your code chain the events together.

The ConnectionID parameter specifies in which SFTP session the request was received, and Path indicates the requested directory.

The following operation status constants are available, besides the ones referenced above:

ostOk	1
ostNoSuchFile	2
ostAccessDenied	3
ostWriteProtect	4
ostUnsupported	5
ostInvalidParameter	6
ostEOF	7