RWFtpsClient Class Reference

Provides low-level access to the FTPS (FTP with SSL) client-side protocol. More...

#include <rw/ftps/RWFtpsClient.h>

Public Member Functions
	RWFtpsClient (const RWSecureSocketContext &context)
RWFtpsDataReply	appe (const RWCString &fspec, int port=0)
RWFtpsReply	auth (void)
RWFtpsReply	cdup (void)
RWFtpsReply	connect (const RWSockAddrBase &address)
RWFtpsReply	cwd (const RWCString &dir)
RWFtpsReply	dataAbort (void)
RWFtpsReply	dataClose (void)
RWFtpsReply	dataUrgentAbort (void)
RWFtpsReply	dele (const RWCString &fspec)
RWFtpsReply	exec (const RWCString &cmdarg)
RWFtpsReply	feat (void)
unsigned long	getTimeout (void) const
RWFtpsReply	help (const RWCString &specificCmd="")
RWFtpsDataReply	list (const RWCString &path="", int port=0)
RWFtpsReply	mkd (const RWCString &fspec)
RWFtpsDataReply	nlst (const RWCString &path="", int port=0)
RWFtpsReply	noop (void)
RWFtpsReply	pass (const RWCString &pass)
RWFtpsReply	pbsz (void)
RWFtpsReply	prot (const RWCString &dataChannelProtectionLevel)
RWFtpsPwdReply	pwd (void)
RWFtpsReply	quit (void)
RWFtpsReply	rein (void)
RWFtpsDataReply	retr (const RWCString &fspec, int port=0)
RWFtpsReply	rmd (const RWCString &fspec)
RWFtpsReply	rnfr (const RWCString &fspec)
RWFtpsReply	rnto (const RWCString &fspec)
void	setTimeout (unsigned long timeout)
RWFtpsReply	site (const RWCString &specificSiteInfo="")
RWFtpsDataReply	stor (const RWCString &fspec, int port=0)
RWFtpsDataReply	stou (const RWCString &fileName, int port=0)
RWFtpsReply	syst (void)
RWFtpsReply	type (const RWCString &t)
RWFtpsReply	user (const RWCString &user)

Detailed Description

RWFtpsClient provides low-level access to the FTPS client-side protocol. In most cases, the method names parallel the names of the protocol actions. The RWFtpsClient class maintains a finite state machine to enforce correct FTPS protocol action ordering. In the case of misordered method invocation, an RWProtocolClientCmdSequenceError exception is thrown. All client methods return a particular type of RWFtpsReply. RWFtpsReply and its subclasses, RWFtpsPwdReply and RWFtpsDataReply, contain an encapsulation of the standard FTP protocol reply messages. Each subclass of RWFtpsReply returns additional information specific to that type of protocol reply.

RWFtpsClient objects are lightweight. They are implemented using the interface-implementation idiom. The RWFtpsClient itself is a handle to an implementation that performs the protocol interaction. RWFtpsClient performs actions in a connection-based model.

Methods that construct data transfer connections, such as retr(), appe(), stor(), stou(), list() and nlst(), take a port parameter. The port parameter controls how the data connection is constructed. Its default is 0.

Value of port	Data Connection	Socket Port
-1	Client -> Server	Local port - Auto selected
0 (default)	Server -> Client	Local port - Auto selected
>0	Server -> Client	Local port - Value of port

If the port parameter is 0, RWFtpsClient selects a local port using an internal algorithm. It then negotiates a server-to-client data connection using the internal PORT protocol command, which is one of the FTP protocol commands. If port is greater than 0, RWFtpsClient negotiates a server-to-client data connection to the specified port using the internal PORT protocol command. If the value of port is -1, RWFtpsClient negotiates a client-to-server data connection to the address and port provided by the FTP server by using the internal PASV protocol command.

The direction of data connection is independent of direction of the data transfer. If you have a firewall, you may need to use the client-to-server connection strategy. It is not supported by all FTP servers, though. For most applications, the default value of 0 is best.

Note

Any method that performs a protocol command may throw an RWProtocolClientCmdSequenceError exception if:

• The method is executed without a valid connection (note that this does not apply to the connect() method).
• The server returns a 503 error code (bad command sequence).
• The server returns a 530 error code (not logged in).

Example

#include <rw/cstring.h>
#include <rw/rstream.h>
 
#include <rw/network/RWPortalIStream.h>
#include <rw/network/RWSocketPortal.h>
#include <rw/network/RWWinSockInfo.h>
 
#include <rw/ftps/RWFtpsClient.h>
 
const unsigned char seed[] =
    "123456789012345678901234567890"
    "123456789012345678901234567890"
    "123456789012345678901234567890"
    "123456789012345678901234567890"
    "123456789012345678901234567890";
 
int main() {
  RWWinSockInfo info;
  RWSecureSocketPackageInit secsock;
 
  // Seed the RNG.  Seeding from a const string is not
  // secure and not recommended for a real-world
  // application, however for the purposes of this
  // example is sufficient.
  RWSecureSocketPackageInit::seedRNGFromMemory(seed, sizeof(seed));
 
  try {
    // Establish a secure socket context
    RWSecureSocketContext context;
 
    // Construct a client to connect an FTP server
    RWFtpsClient client(context);
    RWFtpsReply reply = client.connect("ftp.roguewave.com");
    std::cout << reply << std::endl;
 
    // enable SSL
    reply = client.auth();
    std::cout << reply << std::endl;
 
    // secure the data channel
    reply = client.pbsz();
    std::cout << reply << std::endl;
    reply = client.prot("P");
    std::cout << reply << std::endl;
 
    // Establish a login session
    reply = client.user("anonymous");
    std::cout << reply << std::endl;
    reply = client.pass("me@roguewave.com");
    std::cout << reply << std::endl;
 
    // Go to the pub directory
    reply = client.cwd("pub");
    std::cout << reply << std::endl;
 
    // Find out which directory we're in
    reply = client.pwd();
    std::cout << reply << std::endl;
 
    // Shut down the connection
    reply = client.quit();
    std::cout << reply << std::endl;
  } catch (const RWxmsg& m) {
    std::cout << "Error : " << m.why() << std::endl;
  }
  return 0;
}

Constructor & Destructor Documentation

RWFtpsClient()

RWFtpsClient::RWFtpsClient

(

const RWSecureSocketContext &

context

)

Constructs a default RWFtpsClient.

Member Function Documentation

appe()

RWFtpsDataReply RWFtpsClient::appe	(	const RWCString &	fspec,
		int	port = 0 )

Performs the APPE (append file) protocol action. The fspec is the name of the file to be appended to on the server side (if the file does not exist on the server, most FTP servers will create one). First, the method negotiates how to open a data connection. This negotiation is based on the value of the port parameter. For more information on the port parameter, see the Detailed Description section of RWFtpsClient. A successful data-connection negotiation reply is normally in the 1XX family, indicating that a data connection is open for writing. The RWCString should contain 7-bit US-ASCII data.

The method returns an RWFtpsDataReply object that contains an RWPortal which is used to complete the data portion of the protocol transfer. Writing to this portal transfers file data to the server.

To complete the data transfer, call dataClose(). To abort the data transfer, call either dataAbort() or dataUrgentAbort().

Exceptions

RWProtocolClientCmdSequenceError

Thrown if there is an existing open data channel.

auth()

RWFtpsReply RWFtpsClient::auth

(

void

)

Performs the AUTH TLS protocol action. This method is the first part of establishing a secure FTPS connection. A successful reply is normally in the 2XX family. After a successful reply, your application may log in to the FTP server securely using the standard USER/PASS login sequence. Additionally, the data channel may now be made secure using the PBSZ/PROT command sequence.

cdup()

RWFtpsReply RWFtpsClient::cdup

(

void

)

Performs the CDUP (change to parent directory) protocol action. This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply from the command is normally in the 2XX family.

connect()

RWFtpsReply RWFtpsClient::connect

(

const RWSockAddrBase &

address

)

Enables an FTP client to establish a control-connection session with an FTP server. The address parameter must be an address to the FTP server. A successful reply from the server in response to the connection is normally in the 2XX family. Your application should then attempt a login sequence with the user() and pass() methods.

cwd()

RWFtpsReply RWFtpsClient::cwd

(

const RWCString &

dir

)

Performs the CWD (change working directory) protocol action. This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply from the command is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

dataAbort()

RWFtpsReply RWFtpsClient::dataAbort

(

void

)

Performs the ABOR (abort) protocol action. This action is valid during RETR, APPE, STOR, STOU, LIST, or NLST protocol actions. This action notifies the server that a data transfer abort is requested. This version of the command is sent as normal (in-band) data.

This method takes the place of the dataClose() method, so do not call dataClose() after invoking dataAbort().

A successful reply in response to the dataAbort() function is normally in the 2XX family. However, the FTP server can be in one of two states upon receiving the dataAbort() command. If the FTP server completed data service, it replies with code 226 to indicate the command was successful. If the server received the command while data service was in progress, it replies with one of two codes: 426 to indicate that the data service request terminated abnormally, or 226 to indicate that the abort command was successful.

Exceptions

RWProtocolClientCmdSequenceError

Thrown if this command is executed without a valid data connection.

dataClose()

RWFtpsReply RWFtpsClient::dataClose

(

void

)

Performs a close of the data-channel socket. This action is valid only after a successful RETR, APPE, STOR, STOU, LIST or NLST protocol action. A successful reply for the command is normally in the 2XX family.

Exceptions

RWProtocolClientCmdSequenceError

Thrown if this command is executed without a valid data connection.

dataUrgentAbort()

RWFtpsReply RWFtpsClient::dataUrgentAbort

(

void

)

Performs the ABOR (abort) protocol action. This action is valid after an RETR, APPE, STOR, STOU, LIST or NLST protocol action. It notifies the server that a data transfer abort is requested. This version of the command is sent as out-of-band data.

Note

Use of this command is dangerous because some servers abort the entire session if they receive this action after they have finished sending all their data. Try using the in-band version, dataAbort(), first.

This method takes the place of the dataClose() method. Your application should not call dataClose() after invoking dataUrgentAbort().

A successful reply from the server is normally in the 2XX family. However, an FTP server can be in one of two states when it receives the command. If data service was completed, the reply is code 226, which indicates that the abort command was successful. If the server received the command while data service was in progress, it replies with one of two codes: 426, which indicates that the data service request terminated abnormally, or 226, which indicates that the abort command was successful.

Warning

Per RFC-4217 this method is treated as a dataAbort() call when using TLS encryption.

Exceptions

RWProtocolClientCmdSequenceError

Thrown if this command is executed without a valid data connection.

dele()

RWFtpsReply RWFtpsClient::dele

(

const RWCString &

fspec

)

Performs an DELE (delete file) protocol action. This action will remove the file named fspec from the current working directory on the server.

This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

exec()

RWFtpsReply RWFtpsClient::exec

(

const RWCString &

cmdarg

)

Performs a generic protocol command with the cmdarg parameter in command <parameter list> format. This method can be used to access nonstandard FTP protocol actions on the server. Actions executed with this method are assumed to be atomic in the FTP client's finite state machine. This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

feat()

RWFtpsReply RWFtpsClient::feat

(

void

)

Performs the FEAT (list all new FTP features that the server supports beyond those described in RFC 959) protocol action.

The method returns an RWFtpsReply. A successful reply is normally in the 2XX family, and it contains the extended protocol actions understood by the server.

getTimeout()

unsigned long RWFtpsClient::getTimeout

(

void

)

const

Retrieves the current network timeout value (in milliseconds).

help()

RWFtpsReply RWFtpsClient::help

(

const RWCString &

specificCmd = ""

)

Performs the HELP protocol action. This action is valid in two situations: after the control-connection has been established successfully with an FTP server; and after the USER/PASS login negotiation has completed successfully. When the function does not have a parameter (the default), the result is general help information for all FTP commands on the FTP server. When the parameter is a particular FTP command, such as "help list," the result contains help information for the given FTP command. A successful reply is normally in the 2XX family, and it contains the protocol actions understood by the server. The RWCString should contain 7-bit US-ASCII data.

list()

RWFtpsDataReply RWFtpsClient::list	(	const RWCString &	path = "",
		int	port = 0 )

Performs the LIST (list directory) protocol action. The path parameter is a path name that specifies a directory or a file. A null parameter (the default) specifies the current working or the default directory. The RWCString should contain 7-bit US-ASCII data.

This method opens a data connection. The negotiation is based on the value of the port parameter. For more information, see the Detailed Description section of RWFtpsClient. A successful reply of data-connection negotiation is normally in the 1XX family, indicating that a data connection is open for reading.

The method returns an RWFtpsDataReply object that contains an RWPortal which is used to complete the data portion of the protocol transfer. Reading from this portal returns the directory or file listing data. When a read of zero length is returned, the directory listing transfer is complete.

To complete the data transfer, call dataClose(). To abort the data transfer, call either dataAbort() or dataUrgentAbort().

Exceptions

RWProtocolClientCmdSequenceError

Thrown if there is an existing open data channel.

mkd()

RWFtpsReply RWFtpsClient::mkd

(

const RWCString &

fspec

)

Performs an MKD (make directory) protocol action. This action will create a directory named fspec in the current working directory on the server.

This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

nlst()

RWFtpsDataReply RWFtpsClient::nlst	(	const RWCString &	path = "",
		int	port = 0 )

Performs the NLST (name list) protocol action. The path parameter is the path name that specifies a directory. A null parameter (the default) indicates the current working or default directory. The RWCString should contain 7-bit US-ASCII data.

This method opens a data connection. The negotiation is based on the value of the port parameter. For more information, see the Detailed Description section of RWFtpsClient. A successful reply for data-connection negotiation is normally in the 1XX family, indicating that a data connection is open for reading.

The method returns an RWFtpsDataReply object that contains an RWPortal which is used to complete the data portion of the protocol transfer. The data read from this portal is the directory name list. When a read of zero length is returned, the directory name list transfer is complete.

To complete the data transfer, call dataClose(). To abort the data transfer, call either dataAbort() or dataUrgentAbort().

Exceptions

RWProtocolClientCmdSequenceError

Thrown if there is an existing open data channel.

noop()

RWFtpsReply RWFtpsClient::noop

(

void

)

Performs a NOOP (no operation) protocol action. This action is valid in two situations: after the control-connection has been established successfully with an FTP server; and after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family.

pass()

RWFtpsReply RWFtpsClient::pass

(

const RWCString &

pass

)

Performs the PASS (password) protocol action. This is the second half of the USER/PASS login sequence. If your application does not call the USER protocol action first, a command sequence exception is thrown. A successful reply for the command is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

pbsz()

RWFtpsReply RWFtpsClient::pbsz

(

void

)

Performs the PBSZ protocol action. This method sets the protection buffer size to 0 as required by RFC 4217 for FTPS. This command must be followed by the PROT command in order to secure the data channel.

A successful reply is normally in the 2XX family.

prot()

RWFtpsReply RWFtpsClient::prot

(

const RWCString &

dataChannelProtectionLevel

)

Performs the PROT (data channel protection level) protocol action. To enable data channel encryption, dataChannelProtectionLevel should be "P" (private). To disable data channel encryption, dataChannelProtectionLevel should be "C" (clear text). By default, the data channel is unprotected (clear text).

A successful reply is normally in the 2XX family. After a successful reply, the client will use the specified security protection level for all new data channels.

Note

Any existing (open) data channel connections will not be affected by changing this value.

Exceptions

RWProtocolClientError

Thrown if an invalid option is used for the parameter dataChannelProtectionLevel.

pwd()

RWFtpsPwdReply RWFtpsClient::pwd

(

void

)

Performs the PWD (present working directory) protocol action. This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family.

quit()

RWFtpsReply RWFtpsClient::quit

(

void

)

Performs a QUIT (quit, disconnect) protocol action. This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family. After sending a reply, the server disconnects.

rein()

RWFtpsReply RWFtpsClient::rein

(

void

)

Performs a REIN (re-initialize) protocol action. This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family.

retr()

RWFtpsDataReply RWFtpsClient::retr	(	const RWCString &	fspec,
		int	port = 0 )

Performs the RETR (return file) protocol action. The fspec parameter is the name of the file to be retrieved. The RWCString should contain 7-bit US-ASCII data.

This method opens a data connection. This negotiation is based on the value of the port parameter. For more information on the port parameter, see the Detailed Description section of RWFtpsClient. A successful reply of the data-connection negotiation is normally in the 1XX family, indicating that a data connection is open for reading.

The method returns an RWFtpsDataReply object that contains an RWPortal which is used to complete the data portion of the protocol transfer. The data read from this portal is the contents of the specified file. When a read of zero length is returned, the file transfer is complete.

To complete the data transfer, call dataClose(). To abort the data transfer, call either dataAbort() or dataUrgentAbort().

Exceptions

RWProtocolClientCmdSequenceError

Thrown if there is an existing open data channel.

rmd()

RWFtpsReply RWFtpsClient::rmd

(

const RWCString &

fspec

)

Performs an RMD (remove directory) protocol action. This action will remove the directory named fspec from the current working directory on the server.

This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

rnfr()

RWFtpsReply RWFtpsClient::rnfr

(

const RWCString &

fspec

)

Performs an RNFR (rename from) protocol action. This action executes the RNFR half of the RNFR/RNTO command sequence, which instructs the server to rename the file fspec in the current working directory on the server.

This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

rnto()

RWFtpsReply RWFtpsClient::rnto

(

const RWCString &

fspec

)

Performs an RNTO (rename to) protocol action. This action executes the RNTO half of the RNFR/RNTO command sequence, which instructs the server to rename the file specified in the call to rnfr() to file name fspec.

This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

setTimeout()

void RWFtpsClient::setTimeout

(

unsigned long

timeout

)

Sets the network timeout value (in milliseconds).

site()

RWFtpsReply RWFtpsClient::site

(

const RWCString &

specificSiteInfo = ""

)

Performs the SITE (site information) protocol action. This action is valid in two situations: after the control-connection has been established successfully with an FTP server; and after the USER/PASS login negotiation has completed successfully.

A null parameter (the default) returns general site information. The command with a correct, server-understandable specificSiteInfo returns specific information on a specific site topic. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

stor()

RWFtpsDataReply RWFtpsClient::stor	(	const RWCString &	fspec,
		int	port = 0 )

Performs the STOR (store file) protocol action. The fspec parameter is the name of the file to be created on the server side. First, the method negotiates how to open a data connection. This negotiation is based on the value of the port parameter. For more information on the port parameter, see the Detailed Description section of RWFtpsClient. A successful data-connection negotiation reply is normally in the 1XX family, indicating that a data connection is open for writing. The RWCString should contain 7-bit US-ASCII data.

The method returns an RWFtpsDataReply object that contains an RWPortal which is used to complete the data portion of the protocol transfer. Writing to this portal transfers file data to the server.

To complete the data transfer, call dataClose(). To abort the data transfer, call either dataAbort() or dataUrgentAbort().

Exceptions

RWProtocolClientCmdSequenceError

Thrown if there is an existing open data channel.

stou()

RWFtpsDataReply RWFtpsClient::stou	(	const RWCString &	fileName,
		int	port = 0 )

Performs the STOU (store unique) protocol action. First, the method negotiates how to open a data connection. This negotiation is based on the value of the port parameter. For more information on the port parameter, see the Detailed Description section of RWFtpsClient. A successful reply is normally in the 1XX family, indicating that a data connection is open for writing a file named fileName to the server. The RWCString should contain 7-bit US-ASCII data.

The method returns an RWFtpsDataReply object that contains an RWPortal which is used to complete the data portion of the protocol transfer. Writing to this portal transfers file data to the server.

To complete the data transfer, call dataClose(). To abort the data transfer, call either dataAbort() or dataUrgentAbort().

Exceptions

RWProtocolClientCmdSequenceError

Thrown if there is an existing open data channel.

syst()

RWFtpsReply RWFtpsClient::syst

(

void

)

Performs the SYST (system information) protocol action. This action is valid in two situations: after the control-connection has been established successfully with an FTP server; and after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family.

type()

RWFtpsReply RWFtpsClient::type

(

const RWCString &

t

)

Performs a TYPE (transfer type) protocol action. The t (transfer mode) parameter may be either A for ASCII or I for BINARY. This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

If an illegal TYPE is used for t, the server will return an error message.

user()

RWFtpsReply RWFtpsClient::user

(

const RWCString &

user

)

Performs the USER (user name) protocol action. This method is the first half of the USER/PASS login sequence. A successful reply is normally in the 2XX family or 3XX family.

A 2XX reply indicates the user is logged in; no further action is required for authentication.

A 3XX reply indicates that a password is required; see the pass() member function.

The RWCString should contain 7-bit US-ASCII data.