RWIFtpAgentRWIAgent
Networking Tools: Thread-hot Internet Classes (int library)
#include <rw/toolpro/ftpa.h>
RWIFtpAgent agent;
RWIFtpAgent agent("tsunami.roguewave.com", "user",
"password");
thr, net, int, tls (and possibly std)
RWIFtpAgent provides basic FTP file and directory access. It deals with more of the details of the FTP protocol than the RWIFtpClient class. However, it does not provide the flexibility of the RWIFtpClient class.
RWIFtpAgent performs actions in a transaction-based model, rather than the connection-based model of the RWIFtpClient. The methods interact with the server by connecting, performing the requested action, and disconnecting. Multiple transactions can be performed before an RWIFtpAgent object gets destroyed. Finally, the destructor cleans up resources.
RWIFtpAgent objects are lightweight. They are implemented using the interface-implementation pattern. The RWIFtpAgent itself is really a handle to an implementation that performs the protocol interaction.
#include <iostream.h>
#include <rw/cstring.h>
#include <rw/toolpro/sockport.h>
#include <rw/toolpro/portstrm.h>
#include <rw/toolpro/winsock.h>
#include <rw/toolpro/ftpa.h>
#include <rw/toolpro/dent.h>
void
main()
{
RWWinSockInfo info;
try {
// Create an agent pointing to roguewave's anonymous
// ftp site
RWIFtpAgent agent("ftp.roguewave.com",
"anonymous",
"me@roguewave.com");
// Force the RWIOUResult<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;
RWIDirEntry de;
// Grab each line of text and pass it to the
// RWIDirEntry object to parse.
while (!istrm.eof()) {
text.readLine(istrm);
de = RWIDirEntry(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() ==
RWIDirEntry::DIRECTORY) {
cout << de.name() << de.time()
<<endl;
}
}
}
}
// Close up the agent
RWBoolean b = agent.dataClose();
}
catch (const RWxmsg& m) {
cout << "Error : " << m.why() << endl;
}
}
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 RWIFtpAgent class sets the transfer mode, if necessary, prior to opening the underlying data channel.
The pre-Tools.h++ Professional enum values (ASCII, BINARY, LAST_XFER_MODE) have been retained, but are deprecated. You can keep the compiler from seeing the old values by defining 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 pre-Tools.h++ Professional enum values ( ACTIVE, PASSIVE ) have been retained, but are deprecated. You can keep the compiler from seeing the old values by defining RW_AVOID_PREPROCESSOR_PROBLEMS.
RWIFtpAgent();
Constructs a default invalid RWIFtpAgent object. Use of the default agent results in an exception. Use the assignment operator to initialize this type of a default RWIFtpAgent.
RWIFtpAgent(const RWCString& host, const RWCString& user,
const RWCString& password);
Constructs an RWIFtpAgent that is ready to use in a subsequent, transactional call. The host 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.
RWIOUResult<RWIFtpReply> 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 directory above (that is, the parent directory). If successful, it returns an RWIOUResult with a 2XX reply. Otherwise it returns an exception.
RWIOUResult<RWBoolean> dataClose();
Returns an RWIOUResult with a redeemable RWBoolean. It closes the data communication channel and negotiates data-channel disconnection with the FTP server. The redeemable RWBoolean returns TRUE if the communication channel was successfully closed. An exception is thrown in the case of an unsuccessful data close. After a call to the method, another RWIFtpAgent transactional method call may be made.
RWIOUResult<RWIFtpReply> 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 RWIOUResult with a 2XX reply. Otherwise it returns an exception.
RWIOUResult<RWSocketPortal>
dir(const RWCString& filepath="",
ConnectMode connMode=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, which is the default, the current directory is presumed. The connMode argument controls data connection negotiation. Selecting ACTIVE negotiates a client-to-server data connection, and selecting PASSIVE (the default) negotiates a server-to-client connection. Note that the connection mode is independent of prior or future transfer direction (for example, put, get, etc.).
The method returns an RWIOUResult with a redeemable 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.
A successful call to this method must be followed by a call to the dataClose method.
RWIOUResult<RWSocketPortal>
get(const RWCString& filepath, ConnectMode connMode=PASSIVE,
TransferMode transMode=LAST_XFER_MODE);
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 ACTIVE negotiates a client-to-server data connection, and selecting PASSIVE (the default) negotiates a server-to-client connection. Note that the connection mode is independent of the transfer direction (for example, put, get, etc.). The transMode argument tells the server the type of data transfer to use, either ASCII or BINARY. If transMode is set to LAST_XFER_MODE, which is the default, the method uses the transfer mode that was previously set. If this is the initial transaction in a session, LAST_XFER_MODE means ASCII.
The method returns an RWIOUResult with a redeemable RWSocketPortal. The RWSocketPortal is used to complete the data portion of the protocol transfer. Reading from the portal transfers the file data to the client.
When all the file data has been successfully written, a call to the dataClose method must follow.
RWIOUResult<RWIFtpReply> 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 RWIOUResult with a 2XX reply. Otherwise it returns an exception.
RWIOUResult<RWIFtpPwdReply> pwd();
Performs a current directory transaction. See the description for RWIFtpPwdReply for details about the return value.
RWIOUResult<RWSocketPortal>
put(const RWCString& filepath, ConnectMode connMode=PASSIVE,
TransferMode transMode=LAST_XFER_MODE);
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 ACTIVE negotiates a client-to-server data connection, and selecting PASSIVE (the default) negotiates a server-to-client connection. Note that the connection mode is independent of transfer direction (put, get, etc.). The transMode argument tells the server the type of data transfer to use, either ASCII or BINARY. The LAST_XFER_MODE setting, which is the default, uses the transfer mode that was previously set. If this is the initial transaction of a session, LAST_XFER_MODE means ASCII.
The method returns an RWIOUResult with a redeemable RWSocketPortal. The RWSocketPortal is used to complete the data portion of the protocol transfer. Writing to this portal transfers the file data to the server. When a read of length zero is returned, the file transfer is complete.
A successful call to this method must be followed by a call to the dataClose method.
RWIOUResult<RWIFtpReply> rename(const RWCString& fileFrom, const RWCString& fileTo);
Performs a "rename a file" transaction in the current directory with the fileFrom argument as the name of an existing file and the fileTo argument as the new name of the file. If successful, it returns an RWIOUResult with a 2XX reply. Otherwise it returns an exception.
RWIOUResult<RWIFtpReply> 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 RWIOUResult with a 2XX reply. Otherwise it returns an exception.
©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.