20.3 File Retrieval: Using the FTP Agent (Part I)

With the concepts of protocol clients, protocol agents, protocol replies, and IOUs in mind, we're ready for our first example.

This program uses mechanisms provided by the FTP agent class RWIFtpAgent for easy-to-use FTP file and directory access. The program creates an FTP agent object which first establishes a connection with an FTP server, and then does login negotiation. Afterwards, an RWSocketPortal object is returned from the agent's get method. All data of the specified remote file is then read off from the socket portal. Finally, the data connection that has been used for the data transfer is closed.

20.3.1 Code and Explanation

Here is a portion of code followed by comments explaining key lines.

try {
  RWIFtpAgent agent("ftp.roguewave.com", 
                    "anonymous", "me@roguewave.com");         // 1
 
  RWSocketPortal sPortal = agent.get("remote_file");          // 2

  RWCString packet;
  while (!(packet=sPortal.recv()).isNull()) {                 // 3
    cout << packet << endl;
  }

  RWBoolean dataClosed = agent.dataClose();                   // 4
}                                                             // 5
catch (const RWxmsg& msg) {                                   // 6
  cout << "ERROR: " << msg.why() << endl;
}

`//1`	Constructs an *RWIFtpAgent* object that connects to an FTP server, and handles the FTP login negotiation sequence.
`//2`	Opens a data connection to the FTP server. The `get()` method automatically handles the login sequence first, then establishes a data connection with the remote server for the file transfer. The call to `get()` returns an IOU for an *RWSocketPortal*. Type conversion is used to redeem the IOU for the actual result `sPortal`, causing the thread to block until this result is available.
`//3`	Receives data on the socket portal until the `recv()` function returns the null string, indicating that no more data is available.
`//4`	Closes the data communication channel established by the `get()` method of *RWIFtpAgent* in `//2`. The `dataClose()` method returns an *RWIOUResult* with a redeemable *RWBoolean* that is immediately redeemed for the actual result `dataClosed`. Notice that the `dataClose()` method needs to be invoked for each data transfer session. This is because the FTP protocol establishes a new data connection for each data transfer session. The connection must be removed afterwards.
`//5`	Disconnects from the FTP server in the agent destructor when the agent object goes out of scope.
`//6`	This `catch` clause catches all the `int` library, the `net` library, and Threads.h++ exceptions that could be thrown from within the `try` block, since all Rogue Wave exceptions are derived from *RWxmsg*. Exceptions can be thrown due to bad server connections, incorrect logins, non-existent remote files, etc.

Now that you are comfortable with some fundamental concepts of the int library, let's move on to the second half of the example, which introduces additional features.