FindFirst Event
This event signifies the start of the custom file listing retrieval mechanism.
Object Oriented Interface
public function fireFindFirst($param);
Procedural Interface
secureblackbox_sftpserver_register_callback($res, 27, array($this, 'fireFindFirst'));
Parameter List
'connectionid'
'path'
'operationstatus'
'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.
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:
ostOk | 1 | |
ostNoSuchFile | 2 | |
ostAccessDenied | 3 | |
ostWriteProtect | 4 | |
ostUnsupported | 5 | |
ostInvalidParameter | 6 | |
ostEOF | 7 |