RWFtpAgent

Module:  Internet Protocols Module   Package:  FTP

RWFtpAgentRWAgent

• Local Index
• Header File
• Description
• Example
• Public Enums
• Public Constructors
• Public Member Functions

Members

append() cd() ConnectMode dataClose()

del() dir() get() getTimeout()

mkdir() put() pwd() rename()

rmdir() RWFtpAgent() setTimeout() TransferMode

#include <rw/ftp/RWFtpAgent.h>

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.

#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/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) {
                       cout << de.name() << de.time()
                                         <<endl;
                    }
                }
            }
        }

        // Close up the agent
        bool b = agent.dataClose();
    }
    catch (const RWxmsg& m) {
        cout << "Error : " << m.why() << 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

enum TransferMode { tmode_ascii,tmode_binary,tmode_latest };

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.

The former enum values (ASCII, BINARY, LAST_XFER_MODE) have been retained, but are deprecated. You can refuse support for these values by defining the macro RW_AVOID_PREPROCESSOR_PROBLEMS.

enum ConnectMode { cmode_active, cmode_passive };

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.

The former enum values (ACTIVE, PASSIVE) have been retained, but are deprecated. You can refuse support for these values by defining the macro RW_AVOID_PREPROCESSOR_PROBLEMS.

RWFtpAgent();

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(const RWSockAddrBase& address, 
                 const RWCString& user,
           const RWCString& password);

Constructs an RWFtpAgent that is ready to use in a subsequent, transactional call. The address argument is the FTP server machine to which the agent connects. The user and password arguments 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. The RWCString should contain 7-bit US-ASCII data.

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

Opens a data connection to the FTP server. The filepath argument 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 argument 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 argument 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 ASCII.

RWTIOUResult<RWFtpReply>
cd(const RWCString& dirPath);

Performs a "change directory" transaction. The dirPath argument 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.

RWTIOUResult<bool>
dataClose();

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.

RWTIOUResult<RWFtpReply>
del(const RWCString& filePath);

Performs a delete file transaction. The filePath argument 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.

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

Opens a data connection to the FTP server. The filepath argument 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 argument 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.

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

Opens a data connection to the FTP server. The filepath argument is a complete path to the file that is to be returned from the server. The connMode argument 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 argument 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 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 written, your application must make a call to the dataClose method. The RWCString should contain 7-bit US-ASCII data.

unsigned long
getTimeout(void) const;

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWFtpReply>
mkdir(const RWCString& dirName);

Performs a make directory transaction in the current directory. The dirName argument 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.

RWTIOUResult<RWFtpPwdReply>
pwd();

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.

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

Opens a data connection to the FTP server. The filepath argument is a complete path to the file that is created on the server. The connMode argument 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 argument 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 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.

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

Performs a rename file transaction in the current directory. The fileFrom argument is the name of an existing file, and the fileTo argument 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.

RWTIOUResult<RWFtpReply>
rmdir(const RWCString& dirName);

Performs a remove directory transaction of a directory under the current directory with the dirName argument 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.

void
setTimeout(unsigned long timeout);

Sets the network timeout value (in milliseconds).

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.