RWFtpClient Class Reference

Provides low-level access to the FTP client-side protocol. More...

#include <rw/ftp/RWFtpClient.h>

Public Member Functions
	RWFtpClient (void)
RWTIOUResult< RWFtpDataReply >	appe (const RWCString &fspec, int port=0)
RWTIOUResult< RWFtpReply >	cdup (void)
RWTIOUResult< RWFtpReply >	connect (const RWSockAddrBase &address)
RWTIOUResult< RWFtpReply >	cwd (const RWCString &dir)
RWTIOUResult< RWFtpReply >	dataAbort (void)
RWTIOUResult< RWFtpReply >	dataClose (void)
RWTIOUResult< RWFtpReply >	dataUrgentAbort (void)
RWTIOUResult< RWFtpReply >	dele (const RWCString &fspec)
RWTIOUResult< RWFtpReply >	exec (const RWCString &cmdarg)
RWTIOUResult< RWFtpReply >	feat (void)
unsigned long	getTimeout (void) const
RWTIOUResult< RWFtpReply >	help (const RWCString &specificCmd="")
RWTIOUResult< RWFtpDataReply >	list (const RWCString &path="", int port=0)
RWTIOUResult< RWFtpReply >	mkd (const RWCString &fspec)
RWTIOUResult< RWFtpDataReply >	nlst (const RWCString &path="", int port=0)
RWTIOUResult< RWFtpReply >	noop (void)
RWTIOUResult< RWFtpReply >	pass (const RWCString &pass)
RWTIOUResult< RWFtpPwdReply >	pwd (void)
RWTIOUResult< RWFtpReply >	quit (void)
RWTIOUResult< RWFtpReply >	rein (void)
RWTIOUResult< RWFtpDataReply >	retr (const RWCString &fspec, int port=0)
RWTIOUResult< RWFtpReply >	rmd (const RWCString &fspec)
RWTIOUResult< RWFtpReply >	rnfr (const RWCString &fspec)
RWTIOUResult< RWFtpReply >	rnto (const RWCString &fspec)
void	setTimeout (unsigned long timeout)
RWTIOUResult< RWFtpReply >	site (const RWCString &specificSiteInfo="")
RWTIOUResult< RWFtpDataReply >	stor (const RWCString &fspec, int port=0)
RWTIOUResult< RWFtpDataReply >	stou (const RWCString &fileName, int port=0)
RWTIOUResult< RWFtpReply >	syst (void)
RWTIOUResult< RWFtpReply >	type (const RWCString &t)
RWTIOUResult< RWFtpReply >	user (const RWCString &user)

Detailed Description

RWFtpClient provides low-level access to the FTP client-side protocol. In most cases, the method names parallel the names of the protocol actions. The RWFtpClient class maintains a finite state machine to enforce correct FTP protocol action ordering. In the case of misordered method invocation, an RWProtocolClientCmdSequenceError exception is thrown. All client methods return redeemable RWTIOUResult instances for a particular type of RWFtpReply. RWFtpReply and its subclasses, RWFtpPwdReply and RWFtpDataReply, contain an encapsulation of the standard FTP protocol reply messages. Specific subclasses of RWFtpReply return additional information specific to those types of protocol replies.

RWFtpClient objects are lightweight. They are implemented using the interface-implementation idiom. The RWFtpClient itself is a handle to an implementation that performs the protocol interaction.

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, RWFtpClient 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, RWFtpClient negotiates a server-to-client data connection to the specified port using the internal PORT protocol command. If the value of port is -1, RWFtpClient 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.

Example

#include <rw/rstream.h>
#include <rw/cstring.h>

#include <rw/network/RWSocketPortal.h>
#include <rw/network/RWPortalIStream.h>
#include <rw/network/RWWinSockInfo.h>

#include <rw/ftp/RWFtpClient.h>

int
main()
{
    RWWinSockInfo info;

    try {
        // Construct a client to connect an FTP server
        RWFtpClient client;
        RWFtpReply reply =
                    client.connect("ftp.roguewave.com");
        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

RWFtpClient::RWFtpClient

(

void

)

Constructs a default RWFtpClient.

Member Function Documentation

RWTIOUResult<RWFtpDataReply> RWFtpClient::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 RWFtpClient. A successful data-connection negotiation reply is normally in the 1XX family, indicating that a data connection is open for writing.

The method returns an RWTIOUResult, which is redeemable for an RWFtpDataReply. The RWFtpDataReply object contains an RWSocketPortal that is used to complete the data portion of the protocol transfer. Writing to this portal transfers file data to the server.

After a successful call to the method, your application must call either dataClose(), dataAbort() or dataUrgentAbort(). The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::dele

(

const RWCString &

fspec

)

Performs an DELE (delete file) protocol action. 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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::feat

(

void

)

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

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 RWFtpClient. 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 RWTIOUResult, which is redeemable for an RWFtpReply. A successful reply is normally in the 2XX family, and it contains the extended protocol actions understood by the server.

unsigned long RWFtpClient::getTimeout

(

void

)

const

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpDataReply> RWFtpClient::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.

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 RWFtpClient. 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 RWTIOUResult, which is redeemable for an RWFtpDataReply. The RWFtpDataReply object contains an RWSocketPortal that 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.

After a successful call to this method, your application must call either dataClose(), dataAbort() or dataUrgentAbort(). The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpReply> RWFtpClient::mkd

(

const RWCString &

fspec

)

Performs an MKD (make 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. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpDataReply> RWFtpClient::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.

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 RWFtpClient. 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 RWTIOUResult, which is redeemable for an RWFtpDataReply. The RWFtpDataReply object contains an RWSocketPortal that 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.

After a successful call to the method, your application must call either dataClose(), dataAbort() or dataUrgentAbort(). The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpPwdReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpDataReply> RWFtpClient::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.

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 RWFtpClient. 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 RWTIOUResult, which is redeemable for an RWFtpDataReply. The RWFtpDataReply object contains an RWSocketPortal that 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.

After a successful call to the method, your application must call either dataClose(), dataAbort() or dataUrgentAbort(). The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpReply> RWFtpClient::rmd

(

const RWCString &

fspec

)

Performs an RMD (remove 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. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpReply> RWFtpClient::rnfr

(

const RWCString &

fspec

)

Performs an RNFR (rename from) protocol action. This action is valid after the USER/PASS login negotiation has completed successfully. A successful reply is normally in the 3XX family. After a successful reply, your application should call RNTO. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpReply> RWFtpClient::rnto

(

const RWCString &

fspec

)

Performs an RNTO (rename to) protocol action. This action is valid after the RNFR protocol action has completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

void RWFtpClient::setTimeout

(

unsigned long

timeout

)

Sets the network timeout value (in milliseconds).

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpDataReply> RWFtpClient::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 RWFtpClient. A successful data-connection negotiation reply is normally in the 1XX family, indicating that a data connection is open for writing.

The method returns an RWTIOUResult, which is redeemable for an RWFtpDataReply. The RWFtpDataReply object contains an RWSocketPortal that is used to complete the data portion of the protocol transfer. Writing to this portal transfers file data to the server.

After a successful call to the method, your application must call either dataClose(), dataAbort() or dataUrgentAbort(). The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpDataReply> RWFtpClient::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 RWFtpClient. A successful reply is normally in the 1XX family, indicating that a data connection is open for writing.

This method returns an RWTIOUResult, which is redeemable for an RWFtpDataReply. The RWFtpDataReply object contains an RWSocketPortal that is used to complete the data portion of the protocol transfer. Writing to this portal transfers file data to the server.

After a successful call to the method, your application must call either dataClose(), dataAbort() or dataUrgentAbort(). The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::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.

RWTIOUResult<RWFtpReply> RWFtpClient::user

(

const RWCString &

user

)

Performs the USER (user name) protocol action. This method is the first half of the USER/PASS login sequence. If the action is not followed by the PASS protocol command, a command sequence exception is thrown. A successful reply is normally in the 3XX family. After a successful reply, your application should call PASS. The RWCString should contain 7-bit US-ASCII data.