An SSH File Transfer Protocol (SFTP) client. More...

#include <D:/private/SFML/SFML/include/SFML/Network/Sftp.hpp>

Classes
class	Result
	SFTP result. More...
class	PathResult
	Result of an operation returning a path. More...
struct	Attributes
	File or directory attributes. More...
class	AttributesResult
	Result of an operation returning attributes. More...
class	ListingResult
	Result of an operation returning a directory listing. More...
struct	SessionInfo
	Structure containing information about an active SFTP session. More...

Public Member Functions
	Sftp ()
	Default constructor.
	~Sftp ()
	Destructor.
	Sftp (const Sftp &)=delete
	Deleted copy constructor.
Sftp &	operator= (const Sftp &)=delete
	Deleted copy assignment.
Result	connect (IpAddress server, unsigned short port=22, const TimeoutWithPredicate &timeout=Time::Zero)
	Connect to the specified SFTP server.
Result	disconnect (const TimeoutWithPredicate &timeout=Time::Zero)
	Disconnect the connection with the server.
std::optional< SessionInfo >	getSessionInfo () const
	Get SSH session information.
Result	login (std::string_view name, std::string_view password, const TimeoutWithPredicate &timeout=Time::Zero)
	Log in using a username and a password.
Result	login (std::string_view name, const char publicKeyData, std::size_t publicKeyLength, const char privateKeyData, std::size_t privateKeyLength, const char *privateKeyPassphrase="", const TimeoutWithPredicate &timeout=Time::Zero)
	Log in using a public/private key pair.
Result	login (std::string_view name, std::string_view publicKeyData, std::string_view privateKeyData, std::string_view privateKeyPassphrase={}, const TimeoutWithPredicate &timeout=Time::Zero)
	Log in using a public/private key pair.
PathResult	resolvePath (const std::filesystem::path &path, const TimeoutWithPredicate &timeout=Time::Zero)
	Resolve a remote path into an absolute remote path.
PathResult	getWorkingDirectory (const TimeoutWithPredicate &timeout=Time::Zero)
	Get the current working directory on the server.
AttributesResult	getAttributes (const std::filesystem::path &path, bool followLinks=true, const TimeoutWithPredicate &timeout=Time::Zero)
	Get the attributes of a remote file or directory.
ListingResult	getDirectoryListing (const std::filesystem::path &path, const TimeoutWithPredicate &timeout=Time::Zero)
	Get the contents of the given directory.
Result	createDirectory (const std::filesystem::path &path, std::filesystem::perms permissions=(std::filesystem::perms::owner_all\|std::filesystem::perms::group_read\|std::filesystem::perms::group_exec\|std::filesystem::perms::others_read\|std::filesystem::perms::others_exec), const TimeoutWithPredicate &timeout=Time::Zero)
	Create a new directory.
Result	deleteDirectory (const std::filesystem::path &path, const TimeoutWithPredicate &timeout=Time::Zero)
	Remove an existing directory.
Result	rename (const std::filesystem::path &oldPath, const std::filesystem::path &newPath, bool overwrite=false, const TimeoutWithPredicate &timeout=Time::Zero)
	Rename an existing file or directory.
Result	deleteFile (const std::filesystem::path &path, const TimeoutWithPredicate &timeout=Time::Zero)
	Remove an existing file.
Result	download (const std::filesystem::path &remotePath, const std::function< bool(const void *data, std::size_t size)> &callback, std::uint64_t offset=0, const TimeoutWithPredicate &timeout=Time::Zero)
	Download a file from the server.
Result	upload (const std::filesystem::path &remotePath, const std::function< bool(void *data, std::size_t &size)> &callback, std::filesystem::perms permissions=(std::filesystem::perms::owner_read\|std::filesystem::perms::owner_write\|std::filesystem::perms::group_read\|std::filesystem::perms::others_read), bool truncate=true, bool append=false, std::uint64_t offset=0, const TimeoutWithPredicate &timeout=Time::Zero)
	Upload a file to the server.

Detailed Description

An SSH File Transfer Protocol (SFTP) client.

sf::Sftp is a very simple SFTP client that allows you to communicate with a SFTP server.

The SFTP protocol allows you to manipulate a remote file system (list files, upload, download, create, remove, ...).

Using the SFTP client consists of 4 parts:

Connecting to the SFTP server
Logging in (either using username and password or public key authentication)
Performing file system operations
Disconnecting (this part can be done implicitly by the destructor)

Every operation returns an SFTP result, which contains the result code and optionally a message describing the result. Some commands such as getAttributes() and getDirectoryListing() return additional data, and use a class derived from sf::Sftp::Result to provide this data. The commonly used filesystem operations are directly provided as member functions.

There are three classes of result values: general result values, SSH specific result values and SFTP specific result values. General result values are returned on success and errors not specific to the SSH or SFTP protocols. If an operation manipulating the remote filesystem fails, an SFTP specific result will be returned describing the reason for the failure. If any error related to the communication channel occurs e.g. key exchange failure or authentication failure an SSH error will be returned.

Because most operations manipulate some part of the remote filesystem these operations, especially upload and download, may take some time to complete. This is important to know if you don't want to block your application while the server is completing the task.

Every operation that relies on network communication can be passed a timeout argument. In the simplest case, this timeout argument can just be a fixed time duration after which the operation should time out if no progress has been made. Because some operations simply due to their nature can take longer than others it might not be possible to use the same timeout value for all operations. If it is anticipated that an operation could take a longer amount of time to complete due to e.g. an unreliable or slow connection, the timeout should be increased so the operation still has the possibility to complete successfully. Passing sf::Time::Zero as a timeout value will cause the operation to block until completion or failure.

If you want to pass sf::Time::Zero to wait indefinitely for an operation to complete but still have the possibility to interrupt the operation e.g. if the user decides to quit the application or interrupt a longer download or upload, the timeout can be constructed from a predicate and polling period. The predicate is a callable that takes no parameters and returns true if the operation should continue or false if the operation should time out. The time between consecutive evaluations of the predicate is specified by the period parameter.

Example of a TimeoutWithPredicate:

bool run = true;

sf::Sftp::TimeoutWithPredicate timeout([&run]{ return run; }, sf::milliseconds(1));

sf::Time::milliseconds

constexpr Time milliseconds(std::int32_t amount)

Construct a time value from a number of milliseconds.

When passed to an operation, the above TimeoutWithPredicate object will keep the operation running as long as run is true. The condition is checked every 1 millisecond. As soon as run is set to false the operation will terminate with a Timeout result.

Remember that attempting to modify variables from across threads will require proper synchronization using e.g. mutexes or atomics.

Because the filesystem operations will be performed on the remote system, the paths passed to the operations should be valid paths on the remote system. To guarantee portability, generic POSIX paths should be used. These use / as the path seperator and . to refer to the current directory and .. to refer to the parent directory.

When logging into the server as a specific user the current directory will be set to the home directory that was specified for that user account. Because it cannot be assumed that the SFTP user is also allowed to log into a shell, changing the current directory from the home directory is not always possible and thus not supported. Thus when specifying paths, it is preferred to always make use of absolute paths when possible. Calling getWorkingDirectory() will return the current directory as an absolute path. Listing the contents of a directory whose path is passed as an absolute path will yield directory listing entries whose paths are extentions of the directory's path and thus also absolute paths. The resolvePath() function can be used to convert relative paths or paths containing links into absolute paths without links.

Usage example:

// Create a new SFTP client
sf::Sftp sftp;
 
// Get the address of the server
const auto addresses = sf::Dns::resolve("sftp.myserver.com");
 
// Check if we have a valid address
if (!addresses.has_value() || addresses->empty())
{
    // Handle no valid address...
}
 
// Connect to the server
sf::Sftp::Result result = sftp.connect(addresses->front());
if (result.isOk())
    std::cout << "Connected" << std::endl;
 
// Check session information and verify server
std::optional<sf::Sftp::SessionInfo> info = sftp.getSessionInfo();
if (info->hostKey.sha256 != expectedSha256)
{
    std::cout << "Server untrusted" << std::endl;
    // Handle untrusted server
}
 
// Log in
result = sftp.login("sftpuser", "dF6Zm89D");
if (result.isOk())
    std::cout << "Logged in" << std::endl;
 
// Print the working directory
sf::Sftp::PathResult directory = sftp.getWorkingDirectory();
if (directory.isOk())
    std::cout << "Working directory: " << directory.getPath().string() << std::endl;
 
// Create a new directory
result = sftp.createDirectory("files");
if (result.isOk())
    std::cout << "Created new directory" << std::endl;
 
// Upload a text file to this new directory
result = sftp.upload("files/newfile.txt", [](void* data, std::size_t& size)
{
    // In your own code, ensure size is big enough to store your data
    // We skip the check here for simplicity
    std::memcpy(data, "Hello World", 11);
    size = 11;
    return false; // End transfer after this block
});
if (response.isOk())
    std::cout << "File uploaded" << std::endl;
 
// Rename file
result = sftp.rename("files/newfile.txt", "files/newfile2.txt");
if (result.isOk())
    std::cout << "Renamed file" << std::endl;
 
// Download a text file from this new directory
std::string text;
result = sftp.download("files/newfile2.txt", [&text](const void* data, std::size_t size)
{
    text.append(static_cast<const char*>(data), size);
    return true; // Continue until all data received
});
if (response.isOk())
    std::cout << "File downloaded: " << text << std::endl;
 
// Delete file
result = sftp.deleteFile("files/newfile2.txt");
if (result.isOk())
    std::cout << "Deleted file" << std::endl;
 
// Delete directory
result = sftp.deleteDirectory("files");
if (result.isOk())
    std::cout << "Deleted directory" << std::endl;
 
// Disconnect from the server (optional)
result = sftp.disconnect();
if (result.isOk())
    std::cout << "Disconnected successfully" << std::endl;

Definition at line 54 of file Sftp.hpp.

Constructor & Destructor Documentation

◆ Sftp() [1/2]

sf::Sftp::Sftp ( )

Default constructor.

◆ ~Sftp()

sf::Sftp::~Sftp ( )

Destructor.

Automatically closes the connection with the server if it is still opened.

◆ Sftp() [2/2]

sf::Sftp::Sftp ( const Sftp & )

delete

Deleted copy constructor.

Member Function Documentation

◆ connect()

Result sf::Sftp::connect	(	IpAddress	server,
		unsigned short	port = 22,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Connect to the specified SFTP server.

The port has a default value of 22, which is the standard port used by the SFTP protocol. This function tries to connect to the server so it may take a while to complete, especially if the server is not reachable. To avoid blocking your application for too long, you can use a timeout. The default value, Time::Zero, means that the system timeout will be used (which is usually pretty long).

Parameters

server	Name or address of the SFTP server to connect to
port	Port used for the connection
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of the connection attempt

See also: disconnect

◆ createDirectory()

Result sf::Sftp::createDirectory	(	const std::filesystem::path &	path,
		std::filesystem::perms	permissions = (std::filesystem::perms::owner_all\|std::filesystem::perms::group_read\|std::filesystem::perms::group_exec\|std::filesystem::perms::others_read\|std::filesystem::perms::others_exec),
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Create a new directory.

The new directory is created as a child of the current working directory.

The default permissions value is equivalent to rwxr-xr-x or 0755 in octal notation.

Parameters

path	Path of the directory to create
permissions	Permissions of the directory to create
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of creating the directory

See also: deleteDirectory, rename

◆ deleteDirectory()

Result sf::Sftp::deleteDirectory	(	const std::filesystem::path &	path,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Remove an existing directory.

Use this function with caution, the directory will be removed permanently!

Parameters

path	Path of the directory to remove
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of removing the directory

See also: createDirectory, rename

◆ deleteFile()

Result sf::Sftp::deleteFile	(	const std::filesystem::path &	path,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Remove an existing file.

Use this function with caution, the file will be removed permanently!

Parameters

path	Path to the file to remove
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of removing the file

See also: rename

◆ disconnect()

Result sf::Sftp::disconnect ( const TimeoutWithPredicate & timeout = Time::Zero )

nodiscard

Disconnect the connection with the server.

Parameters

timeout Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of disconnecting the connection with the server

See also: connect

◆ download()

Result sf::Sftp::download	(	const std::filesystem::path &	remotePath,
		const std::function< bool(const void *data, std::size_t size)> &	callback,
		std::uint64_t	offset = 0,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Download a file from the server.

This function retrieves the data in the file at the remote path.

The file data is transferred in sequential blocks. For every block of data transferred, the provided callback is called. The callback is passed a pointer to a data block and the size of the data contained in the current block. This size can change over time so it is important to always check the size value to know how much data is actually available. The callback should return true to indicate to the download function that it should continue to transfer data. If the data transfer should be aborted earlier, false can be returned from the callback.

The function returns once all the data in the remote file has been transferred or an error occurs or the function times out.

If reading from the remote file should not start at the beginning of the file, you can specify an offset in bytes at which reading should start.

Parameters

remotePath	Path of the remote file whose data to download
callback	Callback to be called for every available data block
offset	Byte offset into the remote file at which reading should start
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of downloading the file

See also: upload

◆ getAttributes()

AttributesResult sf::Sftp::getAttributes	(	const std::filesystem::path &	path,
		bool	followLinks = true,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Get the attributes of a remote file or directory.

Depending on whether path refers to a file or directory, the attributes can contain e.g. the type of file, the file owner, group, file size, modification and access times.

If links are not to be followed, followLinks can be set to false. In this case the attributes of the link itself will be returned.

Parameters

path	Path to the remote file or directory whose attributes to get
followLinks	true to follow links, false to return attributes of the link itself
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of getting the attributes

See also: getDirectoryListing

◆ getDirectoryListing()

ListingResult sf::Sftp::getDirectoryListing	(	const std::filesystem::path &	path,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Get the contents of the given directory.

This function retrieves the sub-directories and files contained in the given directory. It is not recursive.

Parameters

path	Path of the directory whose contents to list
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of getting the contents of the given directory

See also: getAttributes

◆ getSessionInfo()

std::optional< SessionInfo > sf::Sftp::getSessionInfo ( ) const

nodiscard

Get SSH session information.

After connecting to the server and before actually logging in the SSH session information of the underlying connection will be available.

The session information contains among other things the public key identifying the remote host and the connection parameters such as encryption and compression used. The identifiers used follow the RFC 4253 specification.

If the session information is not available std::nullopt will be returned.

Because SSH was developed as a parallel standard to SSL/TLS and automatic host certificate verification wasn't widespread at the time, relying on the user to check the authenticity of the host key was the typical method used to verify that they were connecting to the legitimate host, assuming the private key of the remote host was not compromised.

If connection security is a high priority, examining the parameters and aborting the connection if any weak algorithms are used is also possible.

Returns: SSH session information or std::nullopt if it is not available

◆ getWorkingDirectory()

PathResult sf::Sftp::getWorkingDirectory ( const TimeoutWithPredicate & timeout = Time::Zero )

nodiscard

Get the current working directory on the server.

This is an alias for calling resolvePath(".").

Parameters

timeout Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of getting the current working directory

See also: resolvePath

◆ login() [1/3]

Result sf::Sftp::login	(	std::string_view	name,
		const char *	publicKeyData,
		std::size_t	publicKeyLength,
		const char *	privateKeyData,
		std::size_t	privateKeyLength,
		const char *	privateKeyPassphrase = "",
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Log in using a public/private key pair.

Logging in is mandatory after connecting to the server. Users that are not logged in cannot perform any operation.

This overload allows logging into the SFTP server using public key authentication.

The public and private key data should be provided in PEM format. PEM encoded data can be easily recognized by their -----BEGIN ............----- header and -----END ............----- footer.

Even though it is technically possible to derive the public key from the private key, due to backend limitations, providing a pre-generated public key as well is necessary for this function to be able to succeed.

If the private key is protected by a passphrase the passphrase can be provided as a NULL terminated string. If the private key is not protected by a passphrase the passphrase should be set to the empty string.

Parameters

name	User name
publicKeyData	Public key data
publicKeyLength	Public key data length
privateKeyData	Private key data
privateKeyLength	Private key data length
privateKeyPassphrase	Private key passphrase, NULL terminated
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of attempting to log in to the server

◆ login() [2/3]

Result sf::Sftp::login	(	std::string_view	name,
		std::string_view	password,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Log in using a username and a password.

Logging in is mandatory after connecting to the server. Users that are not logged in cannot perform any operation.

Parameters

name	User name
password	Password
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of attempting to log in to the server

◆ login() [3/3]

Result sf::Sftp::login	(	std::string_view	name,
		std::string_view	publicKeyData,
		std::string_view	privateKeyData,
		std::string_view	privateKeyPassphrase = {},
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Log in using a public/private key pair.

Logging in is mandatory after connecting to the server. Users that are not logged in cannot perform any operation.

This overload allows logging into the SFTP server using public key authentication.

The public and private key data should be provided in PEM format. PEM encoded data can be easily recognized by their -----BEGIN ............----- header and -----END ............----- footer.

Even though it is technically possible to derive the public key from the private key, due to backend limitations, providing a pre-generated public key as well is necessary for this function to be able to succeed.

If the private key is protected by a passphrase the passphrase can be provided as a NULL terminated string. If the private key is not protected by a passphrase the passphrase should be set to the empty string.

Parameters

name	User name
publicKeyData	Public key data
privateKeyData	Private key data
privateKeyPassphrase	Private key passphrase
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of attempting to log in to the server

◆ operator=()

Sftp & sf::Sftp::operator= ( const Sftp & )

delete

Deleted copy assignment.

◆ rename()

Result sf::Sftp::rename	(	const std::filesystem::path &	oldPath,
		const std::filesystem::path &	newPath,
		bool	overwrite = false,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Rename an existing file or directory.

In POSIX renaming and moving and synonymous. If you want to move a file or directory from one place to another you rename it from an old to a new path.

If a file exists at the specified new path, depending on whether ovewrite is set to true, the rename operation will overwrite it or not. If a directory is being moved, the new path must either not point to non-existant directory or a directory that is empty. Non-empty directories cannot be overwritten by this operation.

Parameters

oldPath	Old path to the file or directory
newPath	New path to the file or directory
overwrite	Set to true to allow overwriting a file that exists at newPath
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of the operation

◆ resolvePath()

PathResult sf::Sftp::resolvePath	(	const std::filesystem::path &	path,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Resolve a remote path into an absolute remote path.

Paths can contain links and other reserved path identifiers such as . and .. referring to the current directory and parent directory respectively.

When determining the absolute path, which does not contain links or . or .. is necessary, this function can be used.

Resolving "." will return the absolute path to the current working directory of the user after logging in to the SFTP server.

Parameters

path	Path to convert into an absolute path
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of converting the path into an absolute path

See also: getWorkingDirectory

◆ upload()

Result sf::Sftp::upload	(	const std::filesystem::path &	remotePath,
		const std::function< bool(void *data, std::size_t &size)> &	callback,
		std::filesystem::perms	permissions = (std::filesystem::perms::owner_read\|std::filesystem::perms::owner_write\|std::filesystem::perms::group_read\|std::filesystem::perms::others_read),
		bool	truncate = true,
		bool	append = false,
		std::uint64_t	offset = 0,
		const TimeoutWithPredicate &	timeout = Time::Zero )

nodiscard

Upload a file to the server.

This function writes data into a file at the remote path.

The file data is transferred in sequential blocks. Every time the function wants to send a new block of data the provided callback is called. The callback is passed a pointer to a data block and a reference to the size of the data block. Data to be sent should be copied into the data block using e.g. std::memcpy and the size value set to the actual number of bytes copied into the data block. The size of the block can change over time so it is important to check the size value that is passed to the callback to know how many bytes can actually be copied into the data block. The callback should return true to indicate to the upload function that it should continue to transfer data. Once the data transfer should be stopped e.g. because there is no more data left to send, false can be returned from the callback.

The function returns once all the data has been sent or an error occurs or the function times out.

If a file does not exist at the remote path yet, it will be created with the provided permissions.

If a file already exists at the remote path, setting truncate to true will truncate the existing file i.e. delete all pre-existing data before starting to write the new data into the file.

Setting append to true will append to a file if it already exists.

If writing to the remote file should not start at the beginning of the file, you can specify an offset in bytes at which writing should start.

The default permissions value is equivalent to rw-r--r-- or 0644 in octal notation.

Parameters

remotePath	Path of the remote file in which to upload the data
callback	Callback to be called for every available data block
permissions	Permissions of the remote file if it has to be created
truncate	Set to true to truncate the remote file if it already exists
append	Set to true to append to the remote file if it already exists
offset	Byte offset into the remote file at which writing should start
timeout	Maximum time to wait, optionally a predicate can be provided for more fine-grained control

Returns: Result of uploading the file

See also: download

The documentation for this class was generated from the following file:

Sftp.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Sftp() [1/2]

◆ ~Sftp()

◆ Sftp() [2/2]

Member Function Documentation

◆ connect()

◆ createDirectory()

◆ deleteDirectory()

◆ deleteFile()

◆ disconnect()

◆ download()

◆ getAttributes()

◆ getDirectoryListing()

◆ getSessionInfo()

◆ getWorkingDirectory()

◆ login() [1/3]

◆ login() [2/3]

◆ login() [3/3]

◆ operator=()

◆ rename()

◆ resolvePath()

◆ upload()