SFML 3.1.0
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Friends | List of all members
sf::Ftp Class Reference
Network module

A FTP client. More...

`#include <SFML/Network/Ftp.hpp>`

## Classes
class | Response
| FTP response. More...
class | DirectoryResponse
| Specialization of FTP response returning a directory. More...
class | ListingResponse
| Specialization of FTP response returning a file name listing. More...

## Public Types
enum class | TransferMode { Binary , Ascii , Ebcdic }
| Enumeration of transfer modes. More...

## Public Member Functions
| Ftp ()=default
| Default constructor.
| ~Ftp ()
| Destructor.
| Ftp (const Ftp &)=delete
| Deleted copy constructor.
Ftp & | operator= (const Ftp &)=delete
| Deleted copy assignment.
Response | connect (IpAddress server, unsigned short port=21, Time timeout=Time::Zero)
| Connect to the specified FTP server.
Response | disconnect ()
| Close the connection with the server.
Response | login ()
| Log in using an anonymous account.
Response | login (const std::string &name, const std::string &password)
| Log in using a username and a password.
Response | keepAlive ()
| Send a null command to keep the connection alive.
DirectoryResponse | getWorkingDirectory ()
| Get the current working directory.
ListingResponse | getDirectoryListing (const std::string &directory="")
| Get the contents of the given directory.
Response | changeDirectory (const std::string &directory)
| Change the current working directory.
Response | parentDirectory ()
| Go to the parent directory of the current one.
Response | createDirectory (const std::string &name)
| Create a new directory.
Response | deleteDirectory (const std::string &name)
| Remove an existing directory.
Response | renameFile (const std::filesystem::path &file, const std::filesystem::path &newName)
| Rename an existing file.
Response | deleteFile (const std::filesystem::path &name)
| Remove an existing file.
Response | download (const std::filesystem::path &remoteFile, const std::filesystem::path &localPath, TransferMode mode=TransferMode::Binary)
| Download a file from the server.
Response | upload (const std::filesystem::path &localFile, const std::filesystem::path &remotePath, TransferMode mode=TransferMode::Binary, bool append=false)
| Upload a file to the server.
Response | sendCommand (const std::string &command, const std::string &parameter="")
| Send a command to the FTP server.

## Friends
class | DataChannel

## Detailed Description

A FTP client.

sf::Ftp is a very simple FTP client that allows you to communicate with a FTP server.

Deprecated
  Use sf::Sftp if possible.

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

Using the FTP client consists of 4 parts:

- Connecting to the FTP server
- Logging in (either as a registered user or anonymously)
- Sending commands to the server
- Disconnecting (this part can be done implicitly by the destructor)

Every command returns a FTP response, which contains the status code as well as a message from the server. Some commands such as getWorkingDirectory() and getDirectoryListing() return additional data, and use a class derived from sf::Ftp::Response to provide this data. The most often used commands are directly provided as member functions, but it is also possible to use specific commands with the sendCommand() function.

Note that response statuses >= 1000 are not part of the FTP standard, they are generated by SFML when an internal error occurs.

All commands, 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.

Usage example:

// Create a new FTP client
sf::Ftp ftp;
// Get the address of the server
const auto addresses = sf::Dns::resolve("ftp.myserver.com");
// Check if we have a valid address
// Robust code should additionally ensure that the address is IPv4
// since sf::Ftp does not support connecting to IPv6 addresses
if (!addresses.has_value() || addresses->empty())
{
// Handle no valid address...
}
// Connect to the server
sf::Ftp::Response response = ftp.connect(addresses->front());
if (response.isOk())
std::cout << "Connected" << std::endl;
// Log in
response = ftp.login("laurent", "dF6Zm89D");
if (response.isOk())
std::cout << "Logged in" << std::endl;
// Print the working directory
sf::Ftp::DirectoryResponse directory = ftp.getWorkingDirectory();
if (directory.isOk())
std::cout << "Working directory: " << directory.getDirectory() << std::endl;
// Create a new directory
response = ftp.createDirectory("files");
if (response.isOk())
std::cout << "Created new directory" << std::endl;
// Upload a file to this new directory
response = ftp.upload("local-path/file.txt", "files", sf::Ftp::TransferMode::Ascii);
if (response.isOk())
std::cout << "File uploaded" << std::endl;
// Send specific commands (here: FEAT to list supported FTP features)
response = ftp.sendCommand("FEAT");
if (response.isOk())
std::cout << "Feature list:\n" << response.getMessage() << std::endl;
// Disconnect from the server (optional)
ftp.disconnect();
sf::Ftp::DirectoryResponse
Specialization of FTP response returning a directory.
Definition Ftp.hpp:190
sf::Ftp::DirectoryResponse::getDirectory
const std::filesystem::path & getDirectory() const
Get the directory returned in the response.
sf::Ftp::Response
FTP response.
Definition Ftp.hpp:70
sf::Ftp::Response::isOk
bool isOk() const
Check if the status code means a success.
sf::Ftp::Response::getMessage
const std::string & getMessage() const
Get the full message contained in the response.
sf::Ftp
A FTP client.
Definition Ftp.hpp:52
sf::Ftp::TransferMode::Ascii
@ Ascii
Text mode using ASCII encoding.
Definition Ftp.hpp:61
sf::Ftp::createDirectory
Response createDirectory(const std::string &name)
Create a new directory.
sf::Ftp::sendCommand
Response sendCommand(const std::string &command, const std::string &parameter="")
Send a command to the FTP server.
sf::Ftp::connect
Response connect(IpAddress server, unsigned short port=21, Time timeout=Time::Zero)
Connect to the specified FTP server.
sf::Ftp::login
Response login()
Log in using an anonymous account.
sf::Ftp::getWorkingDirectory
DirectoryResponse getWorkingDirectory()
Get the current working directory.
sf::Ftp::disconnect
Response disconnect()
Close the connection with the server.
sf::Ftp::upload
Response upload(const std::filesystem::path &localFile, const std::filesystem::path &remotePath, TransferMode mode=TransferMode::Binary, bool append=false)
Upload a file to the server.
sf::Dns::resolve
std::optional< std::vector< IpAddress > > resolve(const sf::String &hostname, const std::vector< sf::IpAddress > &servers={}, std::optional< sf::Time > timeout=sf::seconds(1))
Resolve a hostname into a list of IP addresses.

Definition at line 51 of file Ftp.hpp.

## Member Enumeration Documentation

## ◆ TransferMode

enum class sf::Ftp::TransferMode
| strong

Enumeration of transfer modes.

Enumerator
Binary | Binary mode (file is transferred as a sequence of bytes).
Ascii | Text mode using ASCII encoding.
Ebcdic | Text mode using EBCDIC encoding.

Definition at line 58 of file Ftp.hpp.

## Constructor & Destructor Documentation

## ◆ Ftp() [1/2]

sf::Ftp::Ftp | ( |  | ) |
| default

Default constructor.

## ◆ ~Ftp()

sf::Ftp::~Ftp | ( |  | ) |

Destructor.

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

## ◆ Ftp() [2/2]

sf::Ftp::Ftp | ( | const Ftp & |  | ) |
| delete

Deleted copy constructor.

## Member Function Documentation

## ◆ changeDirectory()

Response sf::Ftp::changeDirectory | ( | const std::string & | directory | ) |
| nodiscard

Change the current working directory.

The new directory must be relative to the current one.

Parameters

  directory | New working directory

Returns
  Server response to the request

See also
  getWorkingDirectory, getDirectoryListing, parentDirectory

## ◆ connect()

Response sf::Ftp::connect | ( | IpAddress | server,
|  | unsigned short | port = 21,
|  | Time | timeout = Time::Zero )
| nodiscard

Connect to the specified FTP server.

The port has a default value of 21, which is the standard port used by the FTP protocol. You shouldn't use a different value, unless you really know what you do. 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 FTP server to connect to
  port | Port used for the connection
  timeout | Maximum time to wait

Returns
  Server response to the request

See also
  disconnect

## ◆ createDirectory()

Response sf::Ftp::createDirectory | ( | const std::string & | name | ) |
| nodiscard

Create a new directory.

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

Parameters

  name | Name of the directory to create

Returns
  Server response to the request

See also
  deleteDirectory

## ◆ deleteDirectory()

Response sf::Ftp::deleteDirectory | ( | const std::string & | name | ) |
| nodiscard

Remove an existing directory.

The directory to remove must be relative to the current working directory. Use this function with caution, the directory will be removed permanently!

Parameters

  name | Name of the directory to remove

Returns
  Server response to the request

See also
  createDirectory

## ◆ deleteFile()

Response sf::Ftp::deleteFile | ( | const std::filesystem::path & | name | ) |
| nodiscard

Remove an existing file.

The file name must be relative to the current working directory. Use this function with caution, the file will be removed permanently!

Parameters

  name | File to remove

Returns
  Server response to the request

See also
  renameFile

## ◆ disconnect()

Response sf::Ftp::disconnect | ( |  | ) |
| nodiscard

Close the connection with the server.

Returns
  Server response to the request

See also
  connect

## ◆ download()

Response sf::Ftp::download | ( | const std::filesystem::path & | remoteFile,
|  | const std::filesystem::path & | localPath,
|  | TransferMode | mode = TransferMode::Binary )
| nodiscard

Download a file from the server.

The file name of the distant file is relative to the current working directory of the server, and the local destination path is relative to the current directory of your application. If a file with the same file name as the distant file already exists in the local destination path, it will be overwritten.

Parameters

  remoteFile | File name of the distant file to download
  localPath | The directory in which to put the file on the local computer
  mode | Transfer mode

Returns
  Server response to the request

See also
  upload

## ◆ getDirectoryListing()

ListingResponse sf::Ftp::getDirectoryListing | ( | const std::string & | directory = "" | ) |
| 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. The directory parameter is relative to the current working directory.

Parameters

  directory | Directory to list

Returns
  Server response to the request

See also
  getWorkingDirectory, changeDirectory, parentDirectory

## ◆ getWorkingDirectory()

DirectoryResponse sf::Ftp::getWorkingDirectory | ( |  | ) |
| nodiscard

Get the current working directory.

The working directory is the root path for subsequent operations involving directories and/or filenames.

Returns
  Server response to the request

See also
  getDirectoryListing, changeDirectory, parentDirectory

## ◆ keepAlive()

Response sf::Ftp::keepAlive | ( |  | ) |
| nodiscard

Send a null command to keep the connection alive.

This command is useful because the server may close the connection automatically if no command is sent.

Returns
  Server response to the request

## ◆ login() [1/2]

Response sf::Ftp::login | ( |  | ) |
| nodiscard

Log in using an anonymous account.

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

Returns
  Server response to the request

## ◆ login() [2/2]

Response sf::Ftp::login | ( | const std::string & | name,
|  | const std::string & | password )
| 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

Returns
  Server response to the request

## ◆ operator=()

Ftp & sf::Ftp::operator= | ( | const Ftp & |  | ) |
| delete

Deleted copy assignment.

## ◆ parentDirectory()

Response sf::Ftp::parentDirectory | ( |  | ) |
| nodiscard

Go to the parent directory of the current one.

Returns
  Server response to the request

See also
  getWorkingDirectory, getDirectoryListing, changeDirectory

## ◆ renameFile()

Response sf::Ftp::renameFile | ( | const std::filesystem::path & | file,
|  | const std::filesystem::path & | newName )
| nodiscard

Rename an existing file.

The file names must be relative to the current working directory.

Parameters

  file | File to rename
  newName | New name of the file

Returns
  Server response to the request

See also
  deleteFile

## ◆ sendCommand()

Response sf::Ftp::sendCommand | ( | const std::string & | command,
|  | const std::string & | parameter = "" )
| nodiscard

Send a command to the FTP server.

While the most often used commands are provided as member functions in the sf::Ftp class, this method can be used to send any FTP command to the server. If the command requires one or more parameters, they can be specified in parameter. If the server returns information, you can extract it from the response using Response::getMessage().

Parameters

  command | Command to send
  parameter | Command parameter

Returns
  Server response to the request

## ◆ upload()

Response sf::Ftp::upload | ( | const std::filesystem::path & | localFile,
|  | const std::filesystem::path & | remotePath,
|  | TransferMode | mode = TransferMode::Binary,
|  | bool | append = false )
| nodiscard

Upload a file to the server.

The name of the local file is relative to the current working directory of your application, and the remote path is relative to the current directory of the FTP server.

The append parameter controls whether the remote file is appended to or overwritten if it already exists.

Parameters

  localFile | Path of the local file to upload
  remotePath | The directory in which to put the file on the server
  mode | Transfer mode
  append | Pass true to append to or false to overwrite the remote file if it already exists

Returns
  Server response to the request

See also
  download

## Friends And Related Symbol Documentation

## ◆ DataChannel

friend class DataChannel
| friend

Definition at line 549 of file Ftp.hpp.

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

- Ftp.hpp