20.4 File Retrieval: Using the FTP Agent (Part II)

The program in this section 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.

In this example, the get() method creates a separate thread to handle the get functionality without blocking the main execution thread. The main thread can therefore do whatever it needs to do.

When the RWSocketPortal object is needed to complete the file transfer, it can be redeemed for the actual result. The program then uses the RWStreamCoupler mechanism to save the content of the remote file in a local file as specified. Finally, the data connection that has been used for data transfer is closed.

20.4.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
 
  RWIOUResult<RWSocketPortal> sPortal=agent.get("remote_file");// 2

  // Do other things here                                      // 3

  RWPortalIStream istrm(sPortal.redeem());                     // 4
  ofstream ostrm("local file");                                // 5

  RWStreamCoupler couple;                                      // 6
  couple(istrm, ostrm);                                        // 7

  RWBoolean dataClosed = agent.dataClose();                    // 8
}                                                              // 9
catch (const RWxmsg& msg) {                                    //10
  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. It returns an *RWIOUResult* with an *RWSocketPortal* as the redeemable. In fact, an underlying `int` library mechanism creates a new thread that handles the `get()` method separately. An IOU of the method is returned immediately without blocking the main thread. The *RWSocketPortal* can be redeemed later to complete the data portion of the protocol transfer.
`//3`	Handles anything else that might be of interest. This is to show that the application, which is running in the main thread and has nothing to do with the agent's `get()` invocation, can move along without having to wait for the result of the `get()` function.
`//4`	Obtains an *RWSocketPortal* object, by blocking the current thread, then builds an input stream from the socket portal.
`//5`	Constructs an output file stream, which is the destination of the file transfer.
`//6`	Creates an *RWStreamCoupler* object that provides an automated mechanism for connecting an input stream to an output stream.
`//7`	Streams the data from the input stream to the output stream, using the `operator()` method in *RWStreamCoupler*.
`//8`	Closes the data communication channel established by the `get()` method of *RWIFtpAgent* in `//2`.
`//9`	Disconnects from the FTP server when the agent object goes out of scope.
`//10`	This `catch` clause catches all the `int` library, `net` library, and Threads.h++ exceptions that could be thrown from within the `try` block, since all Rogue Wave exceptions are derived from *RWxmsg*.

20.4.2 Further Discussion

For more discussion on the IOU feature and the different ways that IOU results can be redeemed with or without blocking a current thread. For more information, refer to Chapter 19 and the Threads User's Guide.

In the int library, class RWStreamCoupler is a convenience class that provides an automated mechanism for connecting an input stream to an output stream. Used in conjunction with portal streams, it provides coupling between an FTP get() and an FTP put(), an FTP get() and a file, an FTP put() and a file, a POP3 get() and a file, etc. In this instance we are coupling FTP data retrieval to a local file where the data is stored. This mechanism may also be used to automate copying one file to another. Refer to the RWStreamCoupler description in the Tools.h++ Professional Class Reference for further information.

You may have noticed in the above example program that the actual data transfer process, accomplished by the RWStreamCoupler mechanism, has been completed within the main thread. Since no separate thread is created for the data transfer, this could cause a problem when transferring large files. You may want to consider moving all code related to data transfer to a separate function, and using the Threads.h++ thread-creation mechanisms to launch that function in a new thread so the main thread won't be blocked during the data transfer.