Class SFTPClient()

Class for secure network file transfer using SFTP.

SFTP (SSH File Transfer Protocol) is a secure file transfer protocol that operates over SSH, providing encrypted file operations and secure authentication. Instances of the SFTPClient class enable applications to securely transfer files to and from SFTP servers.

A typical usage flow starts with creating an SFTPClient instance using the :new() method, providing the host address, username, and the password.

Two different methods of authentication are supported: via username and password or public-/private key authentication using a key file. When using public-/private key authentication, the password parameter in :new() is ignored. Instead, the :setKeyFile() method must be used to specify the key file used for authentication.

Before establishing the connection, additional security options such as :setKnownHostsFile() for host verification can be configured.

The connection is established by calling :connect(). Once connected, files and their content can be transferred using :put() and :get() and the :putFile() and :getFile() methods, respectively.

Directory operations are handled through the methods :curDir() and :directory().

All operations are executed with the access rights and permissions of the user account that was authenticated when establishing the connection, ensuring that only actions permitted to that user can be performed on the server.

If an operation fails, the error details can be retrieved using the :getLastError() and :getLastMessage() methods.

Possible error situations include network connectivity problems that prevent establishing or maintaining the connection, insufficient permissions of the authenticated SSH user for the requested operation, invalid credentials or issues during SSH key based authentication, and failures in host key verification. Errors may also occur when attempting to delete system-protected directories, create directories within non-existent parent paths, or access directories that do not exist. In addition, invalid path specifications or attempts to remove a non-empty directory will result in operation failure.

Logging and Tracing

The File Transfer asset includes comprehensive logging capabilities that help track operations, diagnose issues, and monitor file transfer activities using the XppRtFileLogger() logging facility. The logging system always captures errors and warnings. Additional logging for different implementation layers can be enabled through the environment variable "xpp.logger". The variable accepts a semicolon-separated list of the following values:

- "sftpclient": Log messages from the SFTP protocol implementation layer

- "sftpclient2.verbose": Enable verbose logging

Initializes a new SFTP client instance.

Establishes a connection.

Creates a directory.

Gets or sets the current working directory.

Deletes a file.

Lists files and directories.

Closes the connection.

Downloads file content.

Downloads a file.

Gets the error code of the last operation.

Gets the error message of the last operation.

Uploads file content.

Uploads a local file.

Removes a directory.

Sets a SSH key file for authentication.

Sets the known hosts file for SSH host verification.

Sets timeout values.

Basic usage example

PROCEDURE Main() 
LOCAL oSFTPClient, aDir 

// Start the file logger. This is required if logging is enabled 
// via the "xpp.logger" environment variable 
XppRtFileLogger():startup() 

// Create the SFTPClient instance 
oSFTPClient := SFTPClient():new("sftp://example.com", "username", "password") 

// Connect to the remote SFTP server 
oSFTPClient:connect() 
? oSFTPClient:getLastError(), oSFTPClient:getLastMessage() 

// Get a list of the files in the current directory 
aDir := oSFTPClient:directory() 
? oSFTPClient:getLastError(), oSFTPClient:getLastMessage() 
AEval( aDir, {|e| QOut(e:Name) } ) 

// Disconnect to clean up resources 
oSFTPClient:disconnect() 

RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Class SFTPClient() Foundation