Loading...
Searching...
No Matches
Sftp.hpp
Go to the documentation of this file.
1
2//
3// SFML - Simple and Fast Multimedia Library
4// Copyright (C) 2007-2026 Laurent Gomila (laurent@sfml-dev.org)
5//
6// This software is provided 'as-is', without any express or implied warranty.
7// In no event will the authors be held liable for any damages arising from the use of this software.
8//
9// Permission is granted to anyone to use this software for any purpose,
10// including commercial applications, and to alter it and redistribute it freely,
11// subject to the following restrictions:
12//
13// 1. The origin of this software must not be misrepresented;
14// you must not claim that you wrote the original software.
15// If you use this software in a product, an acknowledgment
16// in the product documentation would be appreciated but is not required.
17//
18// 2. Altered source versions must be plainly marked as such,
19// and must not be misrepresented as being the original software.
20//
21// 3. This notice may not be removed or altered from any source distribution.
22//
24
25#pragma once
26
28// Headers
30#include <SFML/Network/Export.hpp>
31
32#include <SFML/System/TimeoutWithPredicate.hpp>
33
34#include <array>
35#include <filesystem>
36#include <memory>
37#include <optional>
38#include <string>
39#include <string_view>
40#include <vector>
41
42#include <cstddef>
43#include <cstdint>
44
45
46namespace sf
47{
48class IpAddress;
49
54class SFML_NETWORK_API Sftp
55{
56public:
61 class SFML_NETWORK_API Result
62 {
63 public:
68 enum class Value
69 {
70 // General result values
71 Success,
72 Disconnected,
73 Timeout,
74 Refused,
75 Error,
76
77 // SSH result values
78 BannerReceive,
79 BannerSend,
80 InvalidMac,
81 AllocationFailure,
82 SocketSend,
83 KeyExchangeFailure,
84 HostKeyInitialization,
85 HostKeySign,
86 DecryptError,
87 ProtocolError,
88 PasswordExpired,
89 FileError,
90 MethodNone,
91 AuthenticationFailed,
92 PublicKeyUnverified,
93 ChannelOutOfOrder,
94 ChannelFailure,
95 ChannelRequestDenied,
96 ChannelUnknown,
97 ChannelWindowExceeded,
98 ChannelPacketExceeded,
99 ChannelClosed,
100 ChannelEofSent,
101 ScpProtocol,
102 ZlibError,
103 RequestDenied,
104 MethodNotSupported,
105 InvalidData,
106 PublicKeyProtocol,
107 BufferTooSmall,
108 BadUse,
109 CompressError,
110 OutOfBoundary,
111 AgentProtocol,
112 SocketRecv,
113 EncryptError,
114 BadSocket,
115 KnownHosts,
116 ChannelWindowFull,
117 KeyFileAuthenticationFailed,
118
119 // SFTP result values
120 EndOfFile,
121 NoSuchFile,
122 PermissionDenied,
123 Failure,
124 BadMessage,
125 NoConnection,
126 ConnectionLost,
127 OperationUnsupported,
128 InvalidHandle,
129 NoSuchPath,
130 FileAlreadyExists,
131 WriteProtect,
132 NoMedia,
133 NoSpaceOnFileSystem,
134 QuotaExceeded,
135 UnknownPrincipal,
136 LockConflict,
137 DirectoryNotEmpty,
138 NotADirectory,
139 InvalidFilename,
140 LinkLoop,
141 SftpError
142 };
143
154 explicit Result(Value value, std::string message = "");
155
165 [[nodiscard]] bool isOk() const;
166
173 [[nodiscard]] Value getValue() const;
174
181 [[nodiscard]] const std::string& getMessage() const;
182
183 private:
185 // Member data
187 Value m_value;
188 std::string m_message;
189 };
190
195 class SFML_NETWORK_API PathResult : public Result
196 {
197 public:
205 PathResult(const Result& result, std::filesystem::path path);
206
213 [[nodiscard]] const std::filesystem::path& getPath() const;
214
215 private:
217 // Member data
219 std::filesystem::path m_path;
220 };
221
226 struct Attributes
227 {
228 std::filesystem::path path;
229 std::optional<std::filesystem::file_type> type;
230 std::optional<std::uint64_t> size;
231 std::optional<std::filesystem::perms> permissions;
232 std::optional<std::uint64_t> userId;
233 std::optional<std::uint64_t> groupId;
234 std::optional<std::filesystem::file_time_type> accessTime;
235 std::optional<std::filesystem::file_time_type> modificationTime;
236 };
237
242 class SFML_NETWORK_API AttributesResult : public Result
243 {
244 public:
252 AttributesResult(const Result& result, Attributes attributes);
253
260 [[nodiscard]] const Attributes& getAttributes() const;
261
262 private:
264 // Member data
266 Attributes m_attributes;
267 };
268
273 class SFML_NETWORK_API ListingResult : public Result
274 {
275 public:
283 ListingResult(const Result& result, std::vector<Attributes> listing);
284
291 [[nodiscard]] const std::vector<Attributes>& getListing() const;
292
293 private:
295 // Member data
297 std::vector<Attributes> m_listing;
298 };
299
304 struct SessionInfo
305 {
310 struct HostKey
311 {
312 enum class Type
313 {
314 Unknown,
315 Rsa,
316 Dsa,
317 Ecdsa256,
318 Ecdsa384,
319 Ecdsa521,
320 Ed25519
321 };
322
323 Type type = Type::Unknown;
324 std::vector<std::byte> data;
325 std::array<std::byte, 20> sha1{};
326 std::array<std::byte, 32> sha256{};
327 };
328
329 HostKey hostKey;
330 std::string keyExchangeAlgorithm;
331 std::string hostKeyAlgorithm;
332 std::string clientToServerEncryptionAlgorithm;
333 std::string serverToClientEncryptionAlgorithm;
334 std::string clientToServerMacAlgorithm;
335 std::string serverToClientMacAlgorithm;
336 std::string clientToServerCompressionAlgorithm;
337 std::string serverToClientCompressionAlgorithm;
338 };
339
344 Sftp();
345
353 ~Sftp();
354
359 Sftp(const Sftp&) = delete;
360
365 Sftp& operator=(const Sftp&) = delete;
366
387 [[nodiscard]] Result connect(IpAddress server, unsigned short port = 22, const TimeoutWithPredicate& timeout = Time::Zero);
388
399 [[nodiscard]] Result disconnect(const TimeoutWithPredicate& timeout = Time::Zero);
400
431 [[nodiscard]] std::optional<SessionInfo> getSessionInfo() const;
432
446 [[nodiscard]] Result login(std::string_view name,
447 std::string_view password,
448 const TimeoutWithPredicate& timeout = Time::Zero);
449
485 [[nodiscard]] Result login(std::string_view name,
486 const char* publicKeyData,
487 std::size_t publicKeyLength,
488 const char* privateKeyData,
489 std::size_t privateKeyLength,
490 const char* privateKeyPassphrase = "",
491 const TimeoutWithPredicate& timeout = Time::Zero);
492
526 [[nodiscard]] Result login(std::string_view name,
527 std::string_view publicKeyData,
528 std::string_view privateKeyData,
529 std::string_view privateKeyPassphrase = {},
530 const TimeoutWithPredicate& timeout = Time::Zero);
531
554 [[nodiscard]] PathResult resolvePath(const std::filesystem::path& path, const TimeoutWithPredicate& timeout = Time::Zero);
555
568 [[nodiscard]] PathResult getWorkingDirectory(const TimeoutWithPredicate& timeout = Time::Zero);
569
590 [[nodiscard]] AttributesResult getAttributes(const std::filesystem::path& path,
591 bool followLinks = true,
592 const TimeoutWithPredicate& timeout = Time::Zero);
593
608 [[nodiscard]] ListingResult getDirectoryListing(const std::filesystem::path& path,
609 const TimeoutWithPredicate& timeout = Time::Zero);
610
629 [[nodiscard]] Result createDirectory(
630 const std::filesystem::path& path,
631 std::filesystem::perms permissions = (std::filesystem::perms::owner_all | std::filesystem::perms::group_read |
632 std::filesystem::perms::group_exec | std::filesystem::perms::others_read |
633 std::filesystem::perms::others_exec),
634 const TimeoutWithPredicate& timeout = Time::Zero);
635
650 [[nodiscard]] Result deleteDirectory(const std::filesystem::path& path, const TimeoutWithPredicate& timeout = Time::Zero);
651
674 [[nodiscard]] Result rename(const std::filesystem::path& oldPath,
675 const std::filesystem::path& newPath,
676 bool overwrite = false,
677 const TimeoutWithPredicate& timeout = Time::Zero);
678
693 [[nodiscard]] Result deleteFile(const std::filesystem::path& path, const TimeoutWithPredicate& timeout = Time::Zero);
694
731 [[nodiscard]] Result download(const std::filesystem::path& remotePath,
732 const std::function<bool(const void* data, std::size_t size)>& callback,
733 std::uint64_t offset = 0,
734 const TimeoutWithPredicate& timeout = Time::Zero);
735
791 [[nodiscard]] Result upload(
792 const std::filesystem::path& remotePath,
793 const std::function<bool(void* data, std::size_t& size)>& callback,
794 std::filesystem::perms permissions = (std::filesystem::perms::owner_read | std::filesystem::perms::owner_write |
795 std::filesystem::perms::group_read | std::filesystem::perms::others_read),
796 bool truncate = true,
797 bool append = false,
798 std::uint64_t offset = 0,
799 const TimeoutWithPredicate& timeout = Time::Zero);
800
801private:
803 // Member data
805 struct Impl;
806 std::unique_ptr<Impl> m_impl;
807};
808
809} // namespace sf
810
811
SFML_NETWORK_API
#define SFML_NETWORK_API
Definition Network/Export.hpp:42
sf::IpAddress
Encapsulate an IPv4 network address.
Definition IpAddress.hpp:51
sf::Sftp::AttributesResult
Result of an operation returning attributes.
Definition Sftp.hpp:243
sf::Sftp::AttributesResult::getAttributes
const Attributes & getAttributes() const
Get the attributes.
sf::Sftp::AttributesResult::AttributesResult
AttributesResult(const Result &result, Attributes attributes)
Constructor.
sf::Sftp::ListingResult
Result of an operation returning a directory listing.
Definition Sftp.hpp:274
sf::Sftp::ListingResult::getListing
const std::vector< Attributes > & getListing() const
Get the directory listing.
sf::Sftp::ListingResult::ListingResult
ListingResult(const Result &result, std::vector< Attributes > listing)
Constructor.
sf::Sftp::PathResult
Result of an operation returning a path.
Definition Sftp.hpp:196
sf::Sftp::PathResult::PathResult
PathResult(const Result &result, std::filesystem::path path)
Constructor.
sf::Sftp::PathResult::getPath
const std::filesystem::path & getPath() const
Get the path.
sf::Sftp::Result
SFTP result.
Definition Sftp.hpp:62
sf::Sftp::Result::getValue
Value getValue() const
Get the result value.
sf::Sftp::Result::getMessage
const std::string & getMessage() const
Get the result message.
sf::Sftp::Result::isOk
bool isOk() const
Check if the result is a success.
sf::Sftp::Result::Value
Value
Result values.
Definition Sftp.hpp:69
sf::Sftp::Result::Result
Result(Value value, std::string message="")
Constructor.
sf::Sftp::getDirectoryListing
ListingResult getDirectoryListing(const std::filesystem::path &path, const TimeoutWithPredicate &timeout=Time::Zero)
Get the contents of the given directory.
sf::Sftp::connect
Result connect(IpAddress server, unsigned short port=22, const TimeoutWithPredicate &timeout=Time::Zero)
Connect to the specified SFTP server.
sf::Sftp::login
Result login(std::string_view name, std::string_view password, const TimeoutWithPredicate &timeout=Time::Zero)
Log in using a username and a password.
sf::Sftp::getSessionInfo
std::optional< SessionInfo > getSessionInfo() const
Get SSH session information.
sf::Sftp::getAttributes
AttributesResult getAttributes(const std::filesystem::path &path, bool followLinks=true, const TimeoutWithPredicate &timeout=Time::Zero)
Get the attributes of a remote file or directory.
sf::Sftp::deleteDirectory
Result deleteDirectory(const std::filesystem::path &path, const TimeoutWithPredicate &timeout=Time::Zero)
Remove an existing directory.
sf::Sftp::upload
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.
sf::Sftp::login
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.
sf::Sftp::rename
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.
sf::Sftp::login
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.
sf::Sftp::getWorkingDirectory
PathResult getWorkingDirectory(const TimeoutWithPredicate &timeout=Time::Zero)
Get the current working directory on the server.
sf::Sftp::Sftp
Sftp()
Default constructor.
sf::Sftp::resolvePath
PathResult resolvePath(const std::filesystem::path &path, const TimeoutWithPredicate &timeout=Time::Zero)
Resolve a remote path into an absolute remote path.
sf::Sftp::disconnect
Result disconnect(const TimeoutWithPredicate &timeout=Time::Zero)
Disconnect the connection with the server.
sf::Sftp::createDirectory
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.
sf::Sftp::deleteFile
Result deleteFile(const std::filesystem::path &path, const TimeoutWithPredicate &timeout=Time::Zero)
Remove an existing file.
sf::Sftp::Sftp
Sftp(const Sftp &)=delete
Deleted copy constructor.
sf::Sftp::download
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.
sf::Sftp::operator=
Sftp & operator=(const Sftp &)=delete
Deleted copy assignment.
sf::Sftp::~Sftp
~Sftp()
Destructor.
sf::Time::Zero
static const Time Zero
Predefined "zero" time value.
Definition Time.hpp:110
sf::TimeoutWithPredicate
Utility class providing hybrid functionality of a timeout and a continuation predicate.
Definition TimeoutWithPredicate.hpp:45
sf::Sftp::Attributes
File or directory attributes.
Definition Sftp.hpp:227
sf::Sftp::Attributes::groupId
std::optional< std::uint64_t > groupId
Group ID.
Definition Sftp.hpp:233
sf::Sftp::Attributes::path
std::filesystem::path path
Path to the entry.
Definition Sftp.hpp:228
sf::Sftp::Attributes::accessTime
std::optional< std::filesystem::file_time_type > accessTime
Last access time.
Definition Sftp.hpp:234
sf::Sftp::Attributes::modificationTime
std::optional< std::filesystem::file_time_type > modificationTime
Last modification time.
Definition Sftp.hpp:235
sf::Sftp::Attributes::permissions
std::optional< std::filesystem::perms > permissions
Permissions.
Definition Sftp.hpp:231
sf::Sftp::Attributes::userId
std::optional< std::uint64_t > userId
Owner user ID.
Definition Sftp.hpp:232
sf::Sftp::Attributes::type
std::optional< std::filesystem::file_type > type
Type of the entry.
Definition Sftp.hpp:229
sf::Sftp::Attributes::size
std::optional< std::uint64_t > size
Size of the entry.
Definition Sftp.hpp:230
sf::Sftp::SessionInfo::HostKey
Host key used to identify a host.
Definition Sftp.hpp:311
sf::Sftp::SessionInfo::HostKey::type
Type type
Host key type.
Definition Sftp.hpp:323
sf::Sftp::SessionInfo::HostKey::sha1
std::array< std::byte, 20 > sha1
Host key SHA1 hash.
Definition Sftp.hpp:325
sf::Sftp::SessionInfo::HostKey::sha256
std::array< std::byte, 32 > sha256
Host key SHA256 hash.
Definition Sftp.hpp:326
sf::Sftp::SessionInfo::HostKey::data
std::vector< std::byte > data
Host key data.
Definition Sftp.hpp:324
sf::Sftp::SessionInfo
Structure containing information about an active SFTP session.
Definition Sftp.hpp:305
sf::Sftp::SessionInfo::serverToClientCompressionAlgorithm
std::string serverToClientCompressionAlgorithm
Server to client compression algorithm used in the session (RFC 4253).
Definition Sftp.hpp:337
sf::Sftp::SessionInfo::clientToServerCompressionAlgorithm
std::string clientToServerCompressionAlgorithm
Client to server compression algorithm used in the session (RFC 4253).
Definition Sftp.hpp:336
sf::Sftp::SessionInfo::serverToClientEncryptionAlgorithm
std::string serverToClientEncryptionAlgorithm
Server to client encryption algorithm used in the session (RFC 4253).
Definition Sftp.hpp:333
sf::Sftp::SessionInfo::clientToServerEncryptionAlgorithm
std::string clientToServerEncryptionAlgorithm
Client to server encryption algorithm used in the session (RFC 4253).
Definition Sftp.hpp:332
sf::Sftp::SessionInfo::keyExchangeAlgorithm
std::string keyExchangeAlgorithm
Key exchange algorithm used in the session (RFC 4253).
Definition Sftp.hpp:330
sf::Sftp::SessionInfo::clientToServerMacAlgorithm
std::string clientToServerMacAlgorithm
Client to server message authentication code algorithm used in the session (RFC 4253).
Definition Sftp.hpp:334
sf::Sftp::SessionInfo::hostKey
HostKey hostKey
Host key.
Definition Sftp.hpp:329
sf::Sftp::SessionInfo::hostKeyAlgorithm
std::string hostKeyAlgorithm
Host key algorithm used in the session (RFC 4253).
Definition Sftp.hpp:331
sf::Sftp::SessionInfo::serverToClientMacAlgorithm
std::string serverToClientMacAlgorithm
Server to client message authentication code algorithm used in the session (RFC 4253).
Definition Sftp.hpp:335