SecureBlackbox 2020 Node.js Edition

Questions / Feedback?

FindFirst Event

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

Syntax

sftpserver.on('FindFirst', [callback])

Callback

The 'callback' is called when the 'FindFirst' event is emited.

function(e){ }

The argument 'e' has the following properties:

e.connectionID
e.path
e.operationStatus
e.handle

Remarks

FindFirst, FindNext, and FindClose events represent a mechanism for providing customized file listings to class. They are only fired if Action parameter of the preceding BeforeFind 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. FindFirst fires once to request the first list entry; FindNext 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 FindNext infinitely waiting for the EOF marker.

The handlers for both FindFirst and FindNext 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 ClientFileEntry with the details of the next entry,
  • commit the entry to the server using SetClientFileEntry 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 FindClose 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 FindFirst event handler. This identifier will then be passed to all subsequent FindNext and FindClose 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:

ostOk1
ostNoSuchFile2
ostAccessDenied3
ostWriteProtect4
ostUnsupported5
ostInvalidParameter6
ostEOF7

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 Node.js Edition - Version 20.0 [Build 8165]