Classes | Public Types | Public Member Functions | Friends | List of all members
cpp3ds::Ftp Class Reference

A FTP client. More...

#include <Ftp.hpp>

Inheritance diagram for cpp3ds::Ftp:
cpp3ds::NonCopyable

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. More...
 
Response connect (const IpAddress &server, unsigned short port=21, Time timeout=Time::Zero)
 Connect to the specified FTP server. More...
 
Response disconnect ()
 Close the connection with the server. More...
 
Response login ()
 Log in using an anonymous account. More...
 
Response login (const std::string &name, const std::string &password)
 Log in using a username and a password. More...
 
Response keepAlive ()
 Send a null command to keep the connection alive. More...
 
DirectoryResponse getWorkingDirectory ()
 Get the current working directory. More...
 
ListingResponse getDirectoryListing (const std::string &directory="")
 Get the contents of the given directory. More...
 
Response changeDirectory (const std::string &directory)
 Change the current working directory. More...
 
Response parentDirectory ()
 Go to the parent directory of the current one. More...
 
Response createDirectory (const std::string &name)
 Create a new directory. More...
 
Response deleteDirectory (const std::string &name)
 Remove an existing directory. More...
 
Response renameFile (const std::string &file, const std::string &newName)
 Rename an existing file. More...
 
Response deleteFile (const std::string &name)
 Remove an existing file. More...
 
Response download (const std::string &remoteFile, const std::string &localPath, TransferMode mode=Binary)
 Download a file from the server. More...
 
Response upload (const std::string &localFile, const std::string &remotePath, TransferMode mode=Binary)
 Upload a file to the server. More...
 
Response sendCommand (const std::string &command, const std::string &parameter="")
 Send a command to the FTP server. More...
 

Friends

class DataChannel
 

Detailed Description

A FTP client.

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

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 cpp3ds::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 cpp3ds 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
// Connect to the server
cpp3ds::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
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", cpp3ds::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 46 of file Ftp.hpp.

Member Enumeration Documentation

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 54 of file Ftp.hpp.

Constructor & Destructor Documentation

cpp3ds::Ftp::~Ftp ( )

Destructor.

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

Member Function Documentation

Response cpp3ds::Ftp::changeDirectory ( const std::string &  directory)

Change the current working directory.

The new directory must be relative to the current one.

Parameters
directoryNew working directory
Returns
Server response to the request
See also
getWorkingDirectory, getDirectoryListing, parentDirectory
Response cpp3ds::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
serverName or address of the FTP server to connect to
portPort used for the connection
timeoutMaximum time to wait
Returns
Server response to the request
See also
disconnect
Response cpp3ds::Ftp::createDirectory ( const std::string &  name)

Create a new directory.

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

Parameters
nameName of the directory to create
Returns
Server response to the request
See also
deleteDirectory
Response cpp3ds::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
nameName of the directory to remove
Returns
Server response to the request
See also
createDirectory
Response cpp3ds::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
nameFile to remove
Returns
Server response to the request
See also
renameFile
Response cpp3ds::Ftp::disconnect ( )

Close the connection with the server.

Returns
Server response to the request
See also
connect
Response cpp3ds::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
remoteFileFilename of the distant file to download
localPathThe directory in which to put the file on the local computer
modeTransfer mode
Returns
Server response to the request
See also
upload
ListingResponse cpp3ds::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
directoryDirectory to list
Returns
Server response to the request
See also
getWorkingDirectory, changeDirectory, parentDirectory
DirectoryResponse cpp3ds::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
Response cpp3ds::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
Response cpp3ds::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
Response cpp3ds::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
nameUser name
passwordPassword
Returns
Server response to the request
Response cpp3ds::Ftp::parentDirectory ( )

Go to the parent directory of the current one.

Returns
Server response to the request
See also
getWorkingDirectory, getDirectoryListing, changeDirectory
Response cpp3ds::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
fileFile to rename
newNameNew name of the file
Returns
Server response to the request
See also
deleteFile
Response cpp3ds::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 cpp3ds::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
commandCommand to send
parameterCommand parameter
Returns
Server response to the request
Response cpp3ds::Ftp::upload ( const std::string &  localFile,
const std::string &  remotePath,
TransferMode  mode = Binary 
)

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.

Parameters
localFilePath of the local file to upload
remotePathThe directory in which to put the file on the server
modeTransfer mode
Returns
Server response to the request
See also
download

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