Networking Tools: Thread-hot Internet Classes (int library)
#include <rw/toolpro/ftp.h> RWIFtpClient client;
thr, net, int, tls (and possibly std)
RWIFtpClient provides low-level access to the FTP client-side protocol. In most cases, the method names parallel the names of the protocol actions. The RWIFtpClient class maintains a finite state machine to enforce correct FTP protocol action ordering. In the case of misordered method invocation, an RWxmsg exception is thrown. All client methods return redeemable RWIOUResults for a particular type of RWIFtpReply. RWIFtpReply and its subclasses, RWIFtpPwdReply and RWIFtpDataReply, contain an encapsulation of the standard FTP protocol reply messages. Specific subclasses of RWIFtpReply return additional information specific to those types of protocol replies.
RWIFtpClient objects are lightweight. They are implemented using the interface-implementation pattern. The RWIFtpClient itself is really a handle to an implementation that performs the protocol interaction.
Methods that construct data transfer connections such as retr, stor, stou, list and nlst take a default argument port. The port argument controls how the data connection is constructed.
| 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 argument is 0, which is the default, then RWIFtpClient selects a local port using an internal algorithm and 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, then RWIFtpClient negotiates a server-to-client data connection to the specified port using the internal PORT protocol command. If the value of port is -1, RWIFtpClient negotiates a client-to-server data connection to the address and port provided by the FTP server by using the internal PASV protocol command.
Note that the direction of data connection is not related to that of data transfer, it is purely a connection construction issue. Often users with firewalls may need to use the Client-Server connection strategy. However, this is not supported by all FTP servers. For most users the default value of 0 is best.
#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/ftp.h>
void
main()
{
RWWinSockInfo info;
try {
// Construct a client to connect an FTP server
RWIFtpClient client;
RWIFtpReply reply =
client.connect("ftp.roguewave.com");
cout << reply << endl;
// Establish a login session
reply = client.user("anonymous");
cout << reply << endl;
reply = client.pass("me@roguewave.com");
cout << reply << endl;
// Go to the pub directory
reply = client.cwd("pub");
cout << reply << endl;
// Find out which directory we're in
reply = client.pwd();
cout << reply << endl;
// Shut down the connection
reply = client.quit();
cout << reply << endl;
}
catch (const RWxmsg& m) {
cout << "Error : " << m.why() << endl;
}
}
RWIFtpClient();
Constructs a default RWIFtpClient. You need to use the connect method to connect to an FTP server.
RWIOUResult<RWIFtpReply> cdup();
Performs the CDUP (change to parent directory) protocol action. This action is valid after the user/PASS login negotiation has been successfully completed. A successful reply from the command is normally in the 2XX family.
RWIOUResult<RWIFtpReply> connect(const RWCString& host, int port=21);
Provides the connection method that allows an FTP client to establish a control-connection session with an FTP server. The host argument must be an IP address or host domain name. The port argument must specify which port on the server that the FTP server process is using (normally 21). A successful reply from the server in response to the connection is normally in the 2XX family, signifying that a login sequence should follow by attempting the user and PASS methods.
RWIOUResult<RWIFtpReply> cwd(const RWCString& dir);
Performs the CWD (Change Working Directory) protocol action. This action is valid after the user/PASS login negotiation has been completed successfully. A successful reply from the command is normally in the 2XX family.
RWIOUResult<RWIFtpReply> dataAbort();
Performs the ABOR (Abort) protocol action. This action is valid during RETR, 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, therefore dataClose should not be called after invoking dataAbort.
A successful reply in response to the dataAbort function is normally in the 2XX family, signifying that the abort was successful. Note, however, that 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, then 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.
RWIOUResult<RWIFtpReply> dataClose();
Performs a close of the data-channel socket. This action is valid only after a successful RETR, STOR, STOU, LIST or NLST protocol action. A successful reply for the command is normally in the 2XX family.
RWIOUResult<RWIFtpReply> dataUrgentAbort();
Performs the ABOR (Abort) protocol action. This action is valid after an RETR, STOR, STOU, LIST or NLST protocol action. This action 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 somewhat 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. dataClose should not be attempted after invoking dataUrgentAbort.
A successful reply from the server in response to the command is normally in the 2XX family, signifying that the abort was successful. Note, however, that an FTP server can be in one of two states upon receipt of the command. If data service was completed upon receipt of the dataUrgentAbort command, the reply is code 226, to indicate the abort command was successful. If the server received the command while data service was in progress, there are two reply codes. The first reply is code 426, to indicate the data service request terminated abnormally, and the second reply is code 226, to indicate that the abort command was successful.
RWIOUResult<RWIFtpReply> dele(const RWCString& fspec);
Performs an DELE (Delete File) protocol action. This action is valid after the user/PASS login negotiation has been completed successfully. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpReply> exec(const RWCString& cmdarg);
Performs a generic protocol command with the cmdarg argument 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 been completed successfully. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpReply> help(const RWCString& specificCmd="");
Performs the HELP protocol action. This action is valid in two situations: 1) after the control-connection has been established successfully with an FTP server; and 2) after the user/PASS login negotiation has been completed successfully. When the function has no argument, which is the default, the result is general help information of all possible FTP commands available on the FTP server. When the argument is a particular FTP command, (for example, "help list"), the result provides help information on the given FTP command. A successful reply is normally in the 2XX family, and contains the protocol actions understood by the server.
RWIOUResult<RWIFtpDataReply> 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 argument, the default, implies the current working or the default directory.
This method first negotiates how to open a data connection. The negotiation is based on the value of the port argument. For more information, see the general description section of RWIFtpClient. A successful reply of data-connection negotiation is normally in the 1XX family, indicating that a data connection has been opened for reading.
The method returns an RWIOUResult with a redeemable RWIFtpDataReply. The RWIFtpDataReply object contains a socket portal 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.
A successful call to the method must be followed by a call to the dataClose method in normal situations, or to the dataAbort, or dataUrgentAbort in abnormal situations.
RWIOUResult<RWIFtpReply> mkd(const RWCString& fspec);
Performs an MKD (Make Directory) protocol action. This action is valid after the user/PASS login negotiation has been successfully completed. A successful reply of the command is normally in the 2XX family.
RWIOUResult<RWIFtpDataReply> 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 argument, the default, indicates the current working or default directory.
This method first negotiates how to open a data connection. The negotiation is based on the value of the port argument. For more information, see the general description section of RWIFtpClient. A successful reply for data-connection negotiation is normally in the 1XX family, indicating that a data connection has been opened for reading.
The method returns an RWIOUResult with a redeemable RWIFtpDataReply. The RWIFtpDataReply object contains a socket portal that 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 directory name list transfer is complete.
A successful call to this method must be followed by a call to the dataClose method in normal situations, or to the dataAbort, or dataUrgentAbort in abnormal situations.
RWIOUResult<RWIFtpReply> noop();
Performs a NOOP (No Operation) protocol action. This action is valid in two situations: 1) after the control-connection has been established successfully with an FTP server; and 2) after the user/PASS login negotiation has been completed successfully. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpReply> pass(const RWCString& pass);
Performs the PASS (Password) protocol action. This is the second half of the user/PASS login sequence. It must be preceded with a "user" protocol action, or a command sequence exception is thrown. A successful reply for the command is normally in the 2XX family.
RWIOUResult<RWIFtpPwdReply> pwd();
Performs the PWD (Present Working Directory) protocol action. This action is valid after the user/PASS login negotiation has been successfully completed. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpReply> quit();
Performs a QUIT (quit, disconnect) protocol action. This action is valid after the user/PASS login negotiation has been completed successfully. A successful reply is normally in the 2XX family. After sending a reply, the server disconnects.
RWIOUResult<RWIFtpReply> rein();
Performs a REIN (re-initialize) protocol action. This action is valid after the user/PASS login negotiation has been completed successfully. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpDataReply> retr(const RWCString& fspec, int port=0);
Performs the RETR (Return File) protocol action. The fspec argument is the name of the file to be retrieved. It first negotiates how to open a data connection. This negotiation is based on the value of the port argument. For more information on the port argument, see the general description section of RWIFtpClient. A successful reply of the data-connection negotiation is normally in the 1XX family, indicating that a data connection has been opened for reading.
The method returns an RWIOUResult with a redeemable RWIFtpDataReply. The RWIFtpDataReply object contains a socket portal that is used to complete the data portion of the protocol transfer. Reading from this portal returns the file data. When a read of zero length is returned, the file transfer is complete.
A successful call to the method must be followed by a call to the dataClose, in normal situations, or to dataAbort or dataUrgentAbort in abnormal situations.
RWIOUResult<RWIFtpReply> rmd(const RWCString& fspec);
Performs an RMD (Remove Directory) protocol action. This action is valid after the user/PASS login negotiation has been completed successfully. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpReply> rnfr(const RWCString& fspec);
Performs an RNFR (Rename From) protocol action. This action is valid after the user/PASS login negotiation has been successfully completed. A successful reply is normally in 3XX family, signifying that an RNTO action should follow immediately.
RWIOUResult<RWIFtpReply> rnto(const RWCString& fspec);
Performs an RNTO (Rename To) protocol action. This action is valid after the RNFR protocol action has been completed successfully. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpReply> site(const RWCString& specificSiteInfo="");
Performs the SITE (Site Information) protocol action. This action is valid in two situations: 1) after the control-connection has been established successfully with an FTP server; and 2) after the user/PASS login negotiation has been completed successfully. The action with no argument, which is the default, provides general site information, while the command with a correct, server-understandable specificSiteInfo provides specific information on a specific site topic. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpReply> syst();
Performs the SYST (System Information) protocol action. This action is valid in two situations: 1) after the control-connection has been established successfully with an FTP server; and 2) after the user/PASS login negotiation has been completed successfully. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpDataReply> stor(const RWCString& fspec, int port=0);
Performs the STOR (Store File) protocol action. The fspec argument is the name of the file to be created on the server side. The method first negotiates how to open a data connection. This negotiation is based on the value of the port argument. See the discussion of port in the Description section of RWIFtpClient. A successful data-connection negotiation reply is normally in the 2XX family, indicating that a data connection has been opened for writing.
The method returns an RWIOUResult with a redeemable RWIFtpDataReply. The RWIFtpDataReply object contains a socket portal used to complete the data portion of the protocol transfer. Writing to this portal transfers file data to the server.
A successful call to the method must be followed by a call to the dataClose method, in normal situations, or to either the dataAbort or dataUrgentAbort method in abnormal situations.
RWIOUResult<RWIFtpDataReply> stou(const RWCString& fileName, int port=0);
Performs the STOU (Store Unique) protocol action. The method first negotiates how to open a data connection. This negotiation is based on the value of the port argument. See the discussion of port in the Description section of RWIFtpClient. A successful reply is normally in the 2XX family, indicating that a data connection has been opened for writing.
The method returns an RWIOUResult with a redeemable RWIFtpDataReply. The RWIFtpDataReply object contains a socket portal used to complete the data portion of the protocol transfer. Writing to this portal transfers file data to the server.
A successful call to the method must be followed by a call to the dataClose method in normal situations, or to either the dataAbort or dataUrgentAbort method in abnormal situations.
RWIOUResult<RWIFtpReply> type(const RWCString& t);
Performs a TYPE (Transfer Type) protocol action. The t (transfer mode) argument may be either an "A" for ASCII or "I" for BINARY. This action is valid after the user/PASS login negotiation has been completed successfully. A successful reply is normally in the 2XX family.
RWIOUResult<RWIFtpReply> 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, signifying that a PASS action should follow.
©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.