RWFtpClient
Module: Internet Protocols Module Package: FTP
Does not inherit
Local Index
Members
Header File
#include <rw/ftp/RWFtpClient.h>
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 RWTIOUResults 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(), stor(), stou(), list() and nlst(), take a port argument. The port argument 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 argument 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-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");
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;
}
return 0;
}
Public Constructor
RWFtpClient();
Constructs a default RWFtpClient.
Public Member Functions
RWTIOUResult<RWFtpDataReply> 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 argument. For more information on the port argument, see the general 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 copmlete 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 dataAbort or dataUrgentAbort. The RWCString should contain 7-bit US-ASCII data.
RWTIOUResult<RWFtpReply> cdup();
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> connect(const RWSockAddrBase& address);
Enables 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. Your application should then attempt a login sequence with the user and pass methods.
RWTIOUResult<RWFtpReply> 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> 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, 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> 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.
RWTIOUResult<RWFtpReply> dataUrgentAbort();
Performs the ABOR (abort) protocol action. This action is valid after an RETR, 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> 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> 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 completed successfully. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.
unsigned long getTimeout(void) const;
Retrieves the current network timeout value (in milliseconds).
RWTIOUResult<RWFtpReply> 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 an argument (the default), the result is general help information for all FTP commands on the FTP server. When the argument 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> 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) specifies the current working or the default directory.
This method opens a data connection. The negotiation is based on the value of the port argument. For more information, see the general 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 dataAbort or dataUrgentAbort. The RWCString should contain 7-bit US-ASCII data.
RWTIOUResult<RWFtpReply> 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> 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 opens a data connection. The negotiation is based on the value of the port argument. For more information, see the general 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 dataAbort or dataUrgentAbort. The RWCString should contain 7-bit US-ASCII data.
RWTIOUResult<RWFtpReply> noop();
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> 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> pwd();
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> quit();
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> rein();
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> 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.
This method opens 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 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 dataAbort or dataUrgentAbort. The RWCString should contain 7-bit US-ASCII data.
RWTIOUResult<RWFtpReply> 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> 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> 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 setTimeout(unsigned long timeout);
Sets the network timeout value (in milliseconds).
RWTIOUResult<RWFtpReply> 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 argument (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<RWFtpReply> syst();
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<RWFtpDataReply> 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. First, the method 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 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 dataAbort or dataUrgentAbort. The RWCString should contain 7-bit US-ASCII data.
RWTIOUResult<RWFtpDataReply> 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 argument. For more information on the port argument, see the general 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 dataAbort or dataUrgentAbort. The RWCString should contain 7-bit US-ASCII data.
RWTIOUResult<RWFtpReply> type(const RWCString& t);
Performs a TYPE (transfer type) protocol action. The t (transfer mode) argument 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> 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.
© 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.