.. index:: pair: class; EE::Network::Ftp
.. _doxid-class_e_e_1_1_network_1_1_ftp:

class EE::Network::Ftp
======================

.. toctree::
	:hidden:

	enum_EE_Network_Ftp_TransferMode.rst
	class_EE_Network_Ftp_DirectoryResponse.rst
	class_EE_Network_Ftp_ListingResponse.rst
	class_EE_Network_Ftp_Response.rst

Overview
~~~~~~~~

A FTP client. :ref:`More...<details-class_e_e_1_1_network_1_1_ftp>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	#include <ftp.hpp>
	
	class Ftp: private :ref:`EE::NonCopyable<doxid-class_e_e_1_1_non_copyable>` {
	public:
		// enums
	
		enum :ref:`TransferMode<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8>`;

		// classes
	
		class :ref:`DirectoryResponse<doxid-class_e_e_1_1_network_1_1_ftp_1_1_directory_response>`;
		class :ref:`ListingResponse<doxid-class_e_e_1_1_network_1_1_ftp_1_1_listing_response>`;
		class :ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>`;

		// construction
	
		:ref:`~Ftp<doxid-class_e_e_1_1_network_1_1_ftp_1aa2bd715ea07af580db1375fced81f8db>`();

		// methods
	
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`connect<doxid-class_e_e_1_1_network_1_1_ftp_1a9d7f0d50c96583c83fa085e51e35cc15>`(const std::string& server, unsigned short port = 21, bool useTLS = false, bool validateCertificate = true, bool validateHostname = true, const :ref:`Time<doxid-class_e_e_1_1_system_1_1_time>`& timeout = Time::Zero);
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`disconnect<doxid-class_e_e_1_1_network_1_1_ftp_1a5f5784a118419f758cfab2e3ffa6d2be>`();
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`login<doxid-class_e_e_1_1_network_1_1_ftp_1a88c4455ef6eb1e94f510fbb2e852ef29>`();
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`login<doxid-class_e_e_1_1_network_1_1_ftp_1aa2b1613de54b28d1093606669dc7429b>`(const std::string& name, const std::string& password);
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`keepAlive<doxid-class_e_e_1_1_network_1_1_ftp_1a358ef0b1a9587b06f10b1c43aca68227>`();
		:ref:`DirectoryResponse<doxid-class_e_e_1_1_network_1_1_ftp_1_1_directory_response>` :ref:`getWorkingDirectory<doxid-class_e_e_1_1_network_1_1_ftp_1a8ea25b45a3a18b042414c62e7ea05d5b>`();
		:ref:`ListingResponse<doxid-class_e_e_1_1_network_1_1_ftp_1_1_listing_response>` :ref:`getDirectoryListing<doxid-class_e_e_1_1_network_1_1_ftp_1a1cc527de44f2dbe2206102618d75d7d1>`(const std::string& directory = "");
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`changeDirectory<doxid-class_e_e_1_1_network_1_1_ftp_1aae65d3f21eeea403f227fd92c70ca7b0>`(const std::string& directory);
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`parentDirectory<doxid-class_e_e_1_1_network_1_1_ftp_1adf883c0fe2d87c62640a1d1cf43b5050>`();
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`createDirectory<doxid-class_e_e_1_1_network_1_1_ftp_1a3ee7dd4a47fb9f7355f0fab2d24851d6>`(const std::string& name);
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`deleteDirectory<doxid-class_e_e_1_1_network_1_1_ftp_1a5f6670498edb34fa8a1ec73a7c5ff0ea>`(const std::string& name);
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`renameFile<doxid-class_e_e_1_1_network_1_1_ftp_1aafecd7ca71431751275f5b0f9f223304>`(const std::string& file, const std::string& newName);
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`deleteFile<doxid-class_e_e_1_1_network_1_1_ftp_1aabbc5343452ba06ee8c5a8c082845747>`(const std::string& name);
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`download<doxid-class_e_e_1_1_network_1_1_ftp_1aa2d086017b67eadeef0a3b2c629ab235>`(const std::string& remoteFile, const std::string& localPath, :ref:`TransferMode<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8>` mode = :ref:`Binary<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8ac98f9aeed1f4b07371c97d2e76ea56f8>`);
		:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` :ref:`upload<doxid-class_e_e_1_1_network_1_1_ftp_1a74c066ecb460aa290ada0d39fb47bf14>`(const std::string& localFile, const std::string& remotePath, :ref:`TransferMode<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8>` mode = :ref:`Binary<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8ac98f9aeed1f4b07371c97d2e76ea56f8>`, bool append = false);
		const std::string& :ref:`getHostname<doxid-class_e_e_1_1_network_1_1_ftp_1a8873181a60c7c421133b87c5cdb4380e>`() const;
		const bool& :ref:`isTLS<doxid-class_e_e_1_1_network_1_1_ftp_1ae51e935dcbe97fe05541548392dd1903>`() const;
	};
.. _details-class_e_e_1_1_network_1_1_ftp:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

A FTP client.

:ref:`Ftp <doxid-class_e_e_1_1_network_1_1_ftp>` is a very simple FTP client that allows you to communicate with a FTP server. 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 implicitely 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 :ref:`Ftp::Response <doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` to provide this data. 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:
  
  .. ref-code-block:: cpp
  
  	// Create a new FTP client
  	Ftp ftp;
  	
  	// Connect to the server
  	Ftp::Response response = ftp.connect("ftp://ftp.myserver.com");
  	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
  	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", Ftp::Ascii);
  	if (response.isOk())
  	    std::cout << "File uploaded" << std::endl;
  	
  	// Disconnect from the server (optional)
  	ftp.disconnect();

Construction
------------

.. _doxid-class_e_e_1_1_network_1_1_ftp_1aa2bd715ea07af580db1375fced81f8db:
.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	~Ftp()

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

Methods
-------

.. index:: pair: function; connect
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a9d7f0d50c96583c83fa085e51e35cc15:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` connect(const std::string& server, unsigned short port = 21, bool useTLS = false, bool validateCertificate = true, bool validateHostname = true, const :ref:`Time<doxid-class_e_e_1_1_system_1_1_time>`& timeout = Time::Zero)

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).



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- server

		- Hostname or address of the FTP server to connect to

	*
		- port

		- Port used for the connection

	*
		- useTLS

		- force TLS connection for FTPS.

	*
		- validateCertificate

		- Enables certificate validation for https request

	*
		- validateHostname

		- Enables hostname validation for https request

	*
		- timeout

		- Maximum time to wait



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`disconnect <doxid-class_e_e_1_1_network_1_1_ftp_1a5f5784a118419f758cfab2e3ffa6d2be>`

.. index:: pair: function; disconnect
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a5f5784a118419f758cfab2e3ffa6d2be:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` disconnect()

Close the connection with the server.



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`connect <doxid-class_e_e_1_1_network_1_1_ftp_1a9d7f0d50c96583c83fa085e51e35cc15>`

.. index:: pair: function; login
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a88c4455ef6eb1e94f510fbb2e852ef29:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` login()

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.



.. rubric:: Returns:

Server response to the request

.. index:: pair: function; login
.. _doxid-class_e_e_1_1_network_1_1_ftp_1aa2b1613de54b28d1093606669dc7429b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` login(const std::string& name, const std::string& password)

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.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- name

		- User name

	*
		- password

		- Password



.. rubric:: Returns:

Server response to the request

.. index:: pair: function; keepAlive
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a358ef0b1a9587b06f10b1c43aca68227:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` keepAlive()

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.



.. rubric:: Returns:

Server response to the request

.. index:: pair: function; getWorkingDirectory
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a8ea25b45a3a18b042414c62e7ea05d5b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DirectoryResponse<doxid-class_e_e_1_1_network_1_1_ftp_1_1_directory_response>` getWorkingDirectory()

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



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`getDirectoryListing <doxid-class_e_e_1_1_network_1_1_ftp_1a1cc527de44f2dbe2206102618d75d7d1>`, :ref:`changeDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1aae65d3f21eeea403f227fd92c70ca7b0>`, :ref:`parentDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1adf883c0fe2d87c62640a1d1cf43b5050>`

.. index:: pair: function; getDirectoryListing
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a1cc527de44f2dbe2206102618d75d7d1:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`ListingResponse<doxid-class_e_e_1_1_network_1_1_ftp_1_1_listing_response>` getDirectoryListing(const std::string& directory = "")

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.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- directory

		- Directory to list



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`getWorkingDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1a8ea25b45a3a18b042414c62e7ea05d5b>`, :ref:`changeDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1aae65d3f21eeea403f227fd92c70ca7b0>`, :ref:`parentDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1adf883c0fe2d87c62640a1d1cf43b5050>`

.. index:: pair: function; changeDirectory
.. _doxid-class_e_e_1_1_network_1_1_ftp_1aae65d3f21eeea403f227fd92c70ca7b0:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` changeDirectory(const std::string& directory)

Change the current working directory The new directory must be relative to the current one.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- directory

		- New working directory



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`getWorkingDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1a8ea25b45a3a18b042414c62e7ea05d5b>`, :ref:`getDirectoryListing <doxid-class_e_e_1_1_network_1_1_ftp_1a1cc527de44f2dbe2206102618d75d7d1>`, :ref:`parentDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1adf883c0fe2d87c62640a1d1cf43b5050>`

.. index:: pair: function; parentDirectory
.. _doxid-class_e_e_1_1_network_1_1_ftp_1adf883c0fe2d87c62640a1d1cf43b5050:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` parentDirectory()

Go to the parent directory of the current one.



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`getWorkingDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1a8ea25b45a3a18b042414c62e7ea05d5b>`, :ref:`getDirectoryListing <doxid-class_e_e_1_1_network_1_1_ftp_1a1cc527de44f2dbe2206102618d75d7d1>`, :ref:`changeDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1aae65d3f21eeea403f227fd92c70ca7b0>`

.. index:: pair: function; createDirectory
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a3ee7dd4a47fb9f7355f0fab2d24851d6:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` createDirectory(const std::string& name)

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



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- name

		- Name of the directory to create



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`deleteDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1a5f6670498edb34fa8a1ec73a7c5ff0ea>`

.. index:: pair: function; deleteDirectory
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a5f6670498edb34fa8a1ec73a7c5ff0ea:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` deleteDirectory(const std::string& name)

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!



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- name

		- Name of the directory to remove



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`createDirectory <doxid-class_e_e_1_1_network_1_1_ftp_1a3ee7dd4a47fb9f7355f0fab2d24851d6>`

.. index:: pair: function; renameFile
.. _doxid-class_e_e_1_1_network_1_1_ftp_1aafecd7ca71431751275f5b0f9f223304:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` renameFile(const std::string& file, const std::string& newName)

Rename an existing file The filenames must be relative to the current working directory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- file

		- File to rename

	*
		- newName

		- New name of the file



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`deleteFile <doxid-class_e_e_1_1_network_1_1_ftp_1aabbc5343452ba06ee8c5a8c082845747>`

.. index:: pair: function; deleteFile
.. _doxid-class_e_e_1_1_network_1_1_ftp_1aabbc5343452ba06ee8c5a8c082845747:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` deleteFile(const std::string& name)

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!



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- name

		- File to remove



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

RenameFile

.. index:: pair: function; download
.. _doxid-class_e_e_1_1_network_1_1_ftp_1aa2d086017b67eadeef0a3b2c629ab235:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` download(const std::string& remoteFile, const std::string& localPath, :ref:`TransferMode<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8>` mode = :ref:`Binary<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8ac98f9aeed1f4b07371c97d2e76ea56f8>`)

Download a file from the server The filename 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 filename as the distant file already exists in the local destination path, it will be overwritten.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- remoteFile

		- Filename of the distant file to download

	*
		- localPath

		- Where to put to file on the local computer

	*
		- mode

		- Transfer mode



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`upload <doxid-class_e_e_1_1_network_1_1_ftp_1a74c066ecb460aa290ada0d39fb47bf14>`

.. index:: pair: function; upload
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a74c066ecb460aa290ada0d39fb47bf14:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Response<doxid-class_e_e_1_1_network_1_1_ftp_1_1_response>` upload(const std::string& localFile, const std::string& remotePath, :ref:`TransferMode<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8>` mode = :ref:`Binary<doxid-class_e_e_1_1_network_1_1_ftp_1ac1feb507f5e9c746e896dded540070a8ac98f9aeed1f4b07371c97d2e76ea56f8>`, bool append = false)

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.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- localFile

		- Path of the local file to upload

	*
		- remotePath

		- Where to put to file on the server

	*
		- mode

		- Transfer mode

	*
		- append

		- Pass true to append to or false to overwrite the remote file if it already exists



.. rubric:: Returns:

Server response to the request



.. rubric:: See also:

:ref:`download <doxid-class_e_e_1_1_network_1_1_ftp_1aa2d086017b67eadeef0a3b2c629ab235>`

.. index:: pair: function; getHostname
.. _doxid-class_e_e_1_1_network_1_1_ftp_1a8873181a60c7c421133b87c5cdb4380e:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	const std::string& getHostname() const



.. rubric:: Returns:

The server hostname (available only after connect).

.. index:: pair: function; isTLS
.. _doxid-class_e_e_1_1_network_1_1_ftp_1ae51e935dcbe97fe05541548392dd1903:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	const bool& isTLS() const



.. rubric:: Returns:

True if connection is using TLS (available only after connect).