RWFtpAgent Class Reference

Provides basic FTP file and directory access, handling more FTP protocol details than RWFtpClient, but without as much flexibility. More...

#include <rw/ftp/RWFtpAgent.h>

Inherits RWAgent.

Public Types
enum	ConnectMode { ACTIVE , PASSIVE , cmode_active , cmode_passive }
enum	TransferMode {   ASCII , BINARY , LAST_XFER_MODE , tmode_ascii ,   tmode_binary , tmode_latest }

Public Member Functions
	RWFtpAgent (const RWSockAddrBase &address, const RWCString &user, const RWCString &password=RWCString())
	RWFtpAgent (void)
RWTIOUResult< RWSocketPortal >	append (const RWCString &filepath, ConnectMode connMode=RWFtpAgent::cmode_passive, TransferMode transMode=RWFtpAgent::tmode_latest)
RWTIOUResult< RWFtpReply >	cd (const RWCString &dirPath)
RWTIOUResult< bool >	dataClose (void)
RWTIOUResult< RWFtpReply >	del (const RWCString &filePath)
RWTIOUResult< RWSocketPortal >	dir (const RWCString &filepath="", ConnectMode connMode=RWFtpAgent::cmode_passive)
RWTIOUResult< RWSocketPortal >	get (const RWCString &filepath, ConnectMode connMode=RWFtpAgent::cmode_passive, TransferMode transMode=RWFtpAgent::tmode_latest)
unsigned long	getTimeout (void) const
RWTIOUResult< RWFtpReply >	mkdir (const RWCString &dirName)
RWTIOUResult< RWSocketPortal >	put (const RWCString &filepath, ConnectMode connMode=RWFtpAgent::cmode_passive, TransferMode transMode=RWFtpAgent::tmode_latest)
RWTIOUResult< RWFtpPwdReply >	pwd (void)
RWTIOUResult< RWFtpReply >	rename (const RWCString &fileFrom, const RWCString &fileTo)
RWTIOUResult< RWFtpReply >	rmdir (const RWCString &dirName)
void	setTimeout (unsigned long timeout)

Detailed Description

RWFtpAgent provides basic FTP file and directory access. It handles more of the details of the FTP protocol than the RWFtpClient class, but does not have as much flexibility.

RWFtpAgent performs actions in a transaction-based model (in contrast with the connection-based model of the RWFtpClient). The methods interact with the server by connecting, performing the requested action, and disconnecting. Multiple transactions can be performed before an RWFtpAgent object gets destroyed. The destructor cleans up resources.

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

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/ftp/RWFtpAgent.h>
#include <rw/internet/RWDirEntry.h>
 
int main() {
  RWWinSockInfo info;
 
  try {
    // Create an agent pointing to roguewave's anonymous
    // ftp site
    RWFtpAgent agent("ftp.roguewave.com", "anonymous",
                     "me@roguewave.com");
 
    // Force the RWTIOUResult<RWSocketPortal> to redeem
    // immediately for our portal and build an input
    // stream from it.
    RWSocketPortal p = agent.dir();
 
    // Scope the input stream so it won't access the
    // portal after we call dataClose
    {
      RWPortalIStream istrm(p);
      RWCString text;
      RWDirEntry de;
 
      // Grab each line of text and pass it to the
      // RWDirEntry object to parse.
      while (!istrm.eof()) {
        text.readLine(istrm);
        de = RWDirEntry(text);
 
        // If the resulting object is valid and is a
        // directory, output its name and time to
        // the screen.
        if (de.isValid()) {
          if (de.type() == RWDirEntry::DIRECTORY) {
            std::cout << de.name() << de.time() << std::endl;
          }
        }
      }
    }
 
    // Close up the agent
    bool b = agent.dataClose();
  } catch (const RWxmsg& m) {
    std::cout << "Error : " << m.why() << std::endl;
  }
  return 0;
}

Program Output:

bin 01/05/95 12:00:00
dev 11/02/94 12:00:00
etc 01/23/96 12:00:00
incoming 08/02/96 17:26:00
pub 06/21/96 21:26:00
roguewave 06/10/96 22:21:00
user 11/01/94 12:00:00

Member Enumeration Documentation

ConnectMode

enum RWFtpAgent::ConnectMode

Enumerates which peer (client or server) initiates the data channel connection. If cmode_active is selected, the client becomes active and makes the connection to the listening server. If cmode_passive is selected, the server initiates a data connection to the passive client.

Enumerator
ACTIVE	Deprecated As of SourcePro 1, use cmode_active instead.
PASSIVE	Deprecated As of SourcePro 1, use cmode_passive instead.
cmode_active	Active client makes connection to the listening server.
cmode_passive	Server initiates connection to the passive client.

TransferMode

enum RWFtpAgent::TransferMode

Enumerates the type of the intended transfer. If the TransferMode is set to be tmode_latest, it uses the transfer mode (either tmode_ascii or tmode_binary) that was previously set. The RWFtpAgent class sets the transfer mode, if necessary, prior to opening the underlying data channel.

Enumerator
ASCII	Deprecated As of SourcePro 1, use tmode_ascii instead.
BINARY	Deprecated As of SourcePro 1, use tmode_binary instead.
LAST_XFER_MODE	Deprecated As of SourcePro 1, use tmode_latest instead.
tmode_ascii	ASCII transfer mode.
tmode_binary	Binary transfer mode.
tmode_latest	Transfer mode that was previously set (tmode_ascii or tmode_binary).

Constructor & Destructor Documentation

RWFtpAgent() [1/2]

RWFtpAgent::RWFtpAgent

(

void

)

Constructs a default invalid RWFtpAgent object. Redemption of an RWTIOUResult from any call on a default agent throws an exception. Use the assignment operator to initialize a default RWFtpAgent.

RWFtpAgent() [2/2]

RWFtpAgent::RWFtpAgent	(	const RWSockAddrBase &	address,
		const RWCString &	user,
		const RWCString &	password = RWCString() )

Constructs an RWFtpAgent that is ready to use in a subsequent, transactional call. The address parameter is the FTP server machine to which the agent connects. The user and password parameters are the username and password that are used during the FTP login negotiation sequence. When connecting to an anonymous FTP server, use "anonymous" for the username and send a valid e-mail address for the password. If the FTP server does not require a password, the provided password will be ignored. The RWCString should contain 7-bit US-ASCII data.

Member Function Documentation

append()

RWTIOUResult< RWSocketPortal > RWFtpAgent::append	(	const RWCString &	filepath,
		ConnectMode	connMode = RWFtpAgent::cmode_passive,
		TransferMode	transMode = RWFtpAgent::tmode_latest )

Opens a data connection to the FTP server. The filepath parameter is a complete path to the file that will be appended to on the server. If the file does not exist, most FTP servers will create one. The connMode parameter controls data connection negotiation. Selecting cmode_active negotiates a client-to-server data connection, and selecting cmode_passive (the default) negotiates a server-to-client connection. The connection mode is independent of the transfer direction (see the dir() and get() functions). The transMode parameter specifies the type of data transfer: either tmode_ascii or tmode_binary. The tmode_latest setting (the default) uses the transfer mode that was previously set. If this is the initial transaction of a session, tmode_latest means tmode_ascii.

cd()

RWTIOUResult< RWFtpReply > RWFtpAgent::cd

(

const RWCString &

dirPath

)

Performs a "change directory" transaction. The dirPath parameter is the name of the directory to be changed to. If dirPath is .., the directory is changed to the parent directory. If successful, it returns an RWTIOUResult with a 2XX reply code. The RWTIOUResult is redeemable for an RWFtpReply. The RWCString should contain 7-bit US-ASCII data.

dataClose()

RWTIOUResult< bool > RWFtpAgent::dataClose

(

void

)

Returns an RWTIOUResult, which is redeemable for a bool. This method closes the data communication channel and negotiates data-channel disconnection with the FTP server. The redeemable bool is true if the communication channel is successfully closed. After a successful call to this method, another RWFtpAgent transactional method call may be made.

del()

RWTIOUResult< RWFtpReply > RWFtpAgent::del

(

const RWCString &

filePath

)

Performs a delete file transaction. The filePath parameter is the complete path to the file to be deleted. If successful, it returns an RWTIOUResult with a 2XX reply code. The RWTIOUResult is redeemable for an RWFtpReply. The RWCString should contain 7-bit US-ASCII data.

dir()

RWTIOUResult< RWSocketPortal > RWFtpAgent::dir	(	const RWCString &	filepath = "",
		ConnectMode	connMode = RWFtpAgent::cmode_passive )

Opens a data connection to the FTP server. The filepath parameter is a complete path to the directory or file that is to be returned from the server. If the path is null (the default), the current directory is presumed. The connMode parameter controls data connection negotiation. Selecting cmode_active negotiates a client-to-server data connection, and selecting cmode_passive (the default) negotiates a server-to-client connection. The connection mode is independent of the transfer direction (see the put() and get() functions).

If successful, this method returns an RWTIOUResult, which is redeemable for an RWSocketPortal. The RWSocketPortal is used to complete the data portion of the protocol transfer. Reading from this portal returns the directory listing data. When a read of zero length is returned, the data transfer is complete.

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

get()

RWTIOUResult< RWSocketPortal > RWFtpAgent::get	(	const RWCString &	filepath,
		ConnectMode	connMode = RWFtpAgent::cmode_passive,
		TransferMode	transMode = RWFtpAgent::tmode_latest )

Opens a data connection to the FTP server. The filepath parameter is a complete path to the file that is to be returned from the server. The connMode parameter controls data connection negotiation. Selecting cmode_active negotiates a client-to-server data connection, and selecting cmode_passive (the default) negotiates a server-to-client connection. The connection mode is independent of the transfer direction (see the put() and dir() functions). The transMode parameter tells the server the type of data transfer to use, either tmode_ascii or tmode_binary. If transMode is set to tmode_latest, which is the default, the method uses the transfer mode that was previously set. If this is the initial transaction in a session, tmode_latest means tmode_ascii.

If successful, this method returns an RWTIOUResult, which is redeemable for an RWSocketPortal. The RWSocketPortal is used to complete the data portion of the protocol transfer. Reading from the portal transfers the data to the client.

When all the data has been successfully read, your application must make a call to the dataClose() method. The RWCString should contain 7-bit US-ASCII data.

getTimeout()

unsigned long RWFtpAgent::getTimeout

(

void

)

const

Retrieves the current network timeout value (in milliseconds).

mkdir()

RWTIOUResult< RWFtpReply > RWFtpAgent::mkdir

(

const RWCString &

dirName

)

Performs a make directory transaction in the current directory. The dirName parameter is the name of the directory to be created. If successful, it returns an RWTIOUResult with a 2XX reply code. The RWTIOUResult is redeemable for an RWFtpReply. The RWCString should contain 7-bit US-ASCII data.

put()

RWTIOUResult< RWSocketPortal > RWFtpAgent::put	(	const RWCString &	filepath,
		ConnectMode	connMode = RWFtpAgent::cmode_passive,
		TransferMode	transMode = RWFtpAgent::tmode_latest )

Opens a data connection to the FTP server. The filepath parameter is a complete path to the file that is created on the server. The connMode parameter controls data connection negotiation. Selecting cmode_active negotiates a client-to-server data connection, and selecting cmode_passive (the default) negotiates a server-to-client connection. The connection mode is independent of the transfer direction (see the dir() and get() functions). The transMode parameter specifies the type of data transfer: either tmode_ascii or tmode_binary. The tmode_latest setting (the default) uses the transfer mode that was previously set. If this is the initial transaction of a session, tmode_latest means tmode_ascii.

If successful, this method returns an RWTIOUResult, which is redeemable for an RWSocketPortal. The RWSocketPortal is used to complete the data portion of the protocol transfer. Writing to this portal transfers the data to the server. When a read of length zero is returned, the file transfer is complete.

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

pwd()

RWTIOUResult< RWFtpPwdReply > RWFtpAgent::pwd

(

void

)

Performs a current directory transaction. If successful, this method returns an RWTIOUResult, which is redeemable for an RWFtpPwdReply. See the description for RWFtpPwdReply for details about the return value.

rename()

RWTIOUResult< RWFtpReply > RWFtpAgent::rename	(	const RWCString &	fileFrom,
		const RWCString &	fileTo )

Performs a rename file transaction in the current directory. The fileFrom parameter is the name of an existing file, and the fileTo parameter is the new name of the file. If successful, it returns an RWTIOUResult with a 2XX reply code. The RWTIOUResult is redeemable for an RWFtpReply. The RWCString should contain 7-bit US-ASCII data.

rmdir()

RWTIOUResult< RWFtpReply > RWFtpAgent::rmdir

(

const RWCString &

dirName

)

Performs a remove directory transaction of a directory under the current directory with the dirName parameter as the name of the directory to be deleted. If successful, it returns an RWTIOUResult with a 2XX reply code. The RWTIOUResult is redeemable for an RWFtpReply. The RWCString should contain 7-bit US-ASCII data.

setTimeout()

void RWFtpAgent::setTimeout

(

unsigned long

timeout

)

Sets the network timeout value (in milliseconds).