sf::Ftp Class Reference

A FTP client. More...

#include <SFML/Network/Ftp.hpp>

Inheritance diagram for sf::Ftp:

Classes
class	DirectoryResponse
	Specialization of FTP response returning a directory. More...
class	ListingResponse
	Specialization of FTP response returning a filename listing. More...
class	Response
	Define a FTP response. More...

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

Public Member Functions
	~Ftp ()
	Destructor.
Response	connect (const 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::string &file, const std::string &newName)
	Rename an existing file.
Response	deleteFile (const std::string &name)
	Remove an existing file.
Response	download (const std::string &remoteFile, const std::string &localPath, TransferMode mode=Binary)
	Download a file from the server.
Response	upload (const std::string &localFile, const std::string &remotePath, TransferMode mode=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.

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;
 
// Connect to the server
sf::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
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::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();

Definition at line 47 of file Ftp.hpp.

Member Enumeration Documentation

TransferMode

enum sf::Ftp::TransferMode

Enumeration of transfer modes.

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

Definition at line 55 of file Ftp.hpp.

Constructor & Destructor Documentation

~Ftp()

sf::Ftp::~Ftp

(

)

Destructor.

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

Member Function Documentation

changeDirectory()

Response sf::Ftp::changeDirectory

(

const std::string &

directory

)

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	(	const IpAddress &	server,
		unsigned short	port = 21,
		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).

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

)

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

)

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::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!

Parameters

name	File to remove

Returns

Server response to the request

See also

renameFile

disconnect()

Response sf::Ftp::disconnect

(

)

Close the connection with the server.

Returns

Server response to the request

See also

connect

download()

Response sf::Ftp::download	(	const std::string &	remoteFile,
		const std::string &	localPath,
		TransferMode	mode = Binary
	)

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.

Parameters

remoteFile	Filename 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 = ""

)

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

(

)

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

(

)

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

(

)

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
	)

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

parentDirectory()

Response sf::Ftp::parentDirectory

(

)

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::string &	file,
		const std::string &	newName
	)

Rename an existing file.

The filenames 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 = ""
	)

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::string &	localFile,
		const std::string &	remotePath,
		TransferMode	mode = Binary,
		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.

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 Function Documentation

DataChannel

friend class DataChannel

friend

Definition at line 531 of file Ftp.hpp.

---

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

• Ftp.hpp