Chapter 68. Connecting to an FTP server

Index

FTP over SSL
Traversing the server's contents
Downloading files
Uploading, renaming, and deleting files and directories
#include <x/ftp/client.H>

auto socket=x::netaddr::create("ftp.example.com", "ftp")->connect();

auto ftp=x::ftp::client::create(socket);

ftp->login("anonymous", "user@example.com");

// ...

ftp->logout();
      

x::ftp::client and x::ftp::clientptr are a reference and a nullable pointer reference to a reference-counted object that implements an FTP client. In accordance with the usual naming convention, x::ftp::const_client and x::ftp::const_clientptr define references to a constant FTP client object. Only methods that do not write to the FTP server are constant class methods.

create() takes an already-connected socket as a required parameter. The second optional parameter, specifies whether the connection will use the passive form of FTP and defaults to true.

x::ftp::client throws an exception when an error occurs. One of the exceptions could be a timeout waiting for the FTP server to respond. The default timeout configuration gets specified by the x::ftp::client::timeout::read, x::ftp::client::timeout::read_bytes, x::ftp::client::timeout::write, and x::ftp::client::timeout::write_bytes application properties. A timeout exception gets thrown if the given number of bytes is not succesfully read/written from/to the server within a specific amount of time; at which point the connection is no longer usable, and all further FTP operations will throw exceptions immediately.

Polite FTP clients will logout() before disconnecting from the server.

auto socket=x::netaddr("ftp.example.com", "ftp")->connect();

auto timeout=x::fdtimeout::create(socket);

timeout->set_read_timeout(8192, 60);
timeout->set_write_timeout(8192, 30);

auto conn=x::ftp::client::create(netaddr, timeout);

conn->timeout(timeout);
      

create() also takes an optional custom timeout setting. The custom timeout setting is used only for the initial greeting. Use timeout() to permanently install a custom timeout handler, for the connection.

Note that this timeout setting affects the main FTP control channel. All x::ftp::client methods that create a data channel take an optional x::fdtimeoutconfig that gets used to set up a custom timeout for the data channel, for the duration of the method.

create() only waits for the initial greeting from the server. login() logs in using the specified userid and password.

FTP over SSL

#include <x/ftp/client.H>
#include <x/gnutls/credentials.H>

auto socket=x::netaddr::create("ftp.example.com", "ftp")->connect();

auto credentials=x::gnutls::credentials::certificate::create();

credentials->set_x509_trust_default();

auto ftp=x::ftp::client::create(socket, credentials, "ftp.example.com");

Link with -lcxxtls to be able to connect to an FTP server using SSL. See Part VI, “GnuTLS classes” for general information about using SSL and TLS classes. This example expects the server's certificate to be signed by one of the default trusted certificate authorities. For a connection to a server that uses a self-signed or a privately-signed certificate, use set_x509_trust_file() to install the custom certificate, instead.

Pass the credentials object, and the server's known name to create(). The server's known name gets checked against the server's certificate, and an exception gets thrown if the names do not match. Additionally the server's expected name gets sent to the server as part of the initial handshake, so that the server can return the correct certificate (for servers serving multiple domains on the same IP address). Leave out the server name parameter in order to disable the server name check.