Downloading

In addition to Visual Studio C++, you'll need 2 files:

The latest copy of FileCatalyst's C++ API/SDK, available from Unlimi-Tech.
A recent version of Boost. If using Windows, you can download Boost from Sourceforge.

Make sure you download the correct 32-bit or 64-bit files, depending on what you'll be building. In this example, a 64-bit application will be built.

Installing

Install Boost and the FileCatalyst C++ API/SDK. Note the installation directory of FC++, which should default to "C:\Program Files\FCpp\".

Once Installed

A number of links are installed in the "Start" menu, including a link to the entire FC++ API/SDK documentation.

Directories

The location into which FC++ was installed will contain several important directories for C++ development. This includes all of the header files in include and the libraries against which to link in lib.

Unless this was changed during the installation, on Windows the default installation directory should be "C:\Program Files\FCpp\".

Create a Project

Create a new Visual Studio C++ project. For this example, a simple console application will be built.

Project Properties

Several project properties need to be modified to use FC++.

In the Visual Studio Solution Explorer, right-mouse-click on the the application name to edit the properties

Include Directories

Add the Boost and FC++ include directories so Visual Studio can find the necessary header files.

Library Directories

Similarly, add the necessary directory names so Visual Studio can find the necessary libraries.

OpenSSL

FC++ uses OpenSSL for encryption and decryption of streams.

Edit the linker's "Additional Dependencies" and add the two OpenSSL libraries.

Our First FC++ Application

Here is an example application that will perform a simple call into the FC++ library. This will obtain two version numbers. The first is the base FileCatalyst version string, the second is the FC++ library build string.

Transfer Files

Uploading and downloading files doesn't take much code with FC++:

At the simplest, a transfer would typically take 3 lines of code:

fc::Options options( "username", "password", "ftp.example.com" );
fc::Control ftp( options );
ftp.download( fc::Remote( "image.iso" ) );

Similarly, uploading is as easy:

fc::Options options( "username", "password", "ftp.example.com" );
fc::Control ftp( options );
ftp.upload( fc::Local( "backup.zip" ) );

There are 2 central C++ classes in FC++:

fc::Options is used to set or get a number of options that determine how file transfers will take place. These objects are used just once, would typically be built on the stack and allowed to go out of scope after the fc::Control object has been created.
fc::Control represents a connection to a FileCatalyst FTP server, and includes any transfers between the FC++ client and the FC server. These objects can also be built on the stack, but once they go out of scope the connection to the server is closed and any incomplete transfer will be cancelled.

Setting Options

Many options can be set to alter the behaviour of file transfers. All of the options are described in the installed FC++ HTML documentation.

For example:

fc::Options options;
options.setUsernameAndPassword  ( "user", "test"    );
options.setFtpServer            ( "192.168.1.3", 21 );
options.setBandwidth            ( fc::k100_Mbps     );
options.setCongestionControl    ( true              );
options.setMd5Verification      ( true              );
options.setMode                 ( fc::kUdp          );
fc::Control ftp( options );

To see the full list of options that may be set, see the documentation for the C++ class fc::Options as well as suggested Recommendations.

Multiple Files And Directories

Multiple files can ben queued for upload or download. Entire directories can also be easily queued, as well as recursive transfers.

This example shows how to setup multiple transfers, including recursive directory transfers:

fc::Control ftp( options );
ftp.prepareRecursiveDir( fc::Remote("/project_a/")      , fc::Local("C:\\temp_files\\")             );
ftp.prepareRecursiveDir( fc::Remote("/docs/project_a/") , fc::Local("C:\\temp_files\\docs\\")       );
ftp.prepareSingleFile(   fc::Remote("readme.txt")       , fc::Local("C:\\temp_files\\readme_01.txt" );
ftp.download();

For additional information, see fc::Control::prepareRecursiveDir() and fc::Control::prepareSingleFile().

Transfer Statistics

Every transfer is recorded in a fc::TransferStats object.

These statistics can also be accessed while a transfer is on-going to provide realtime information such as transfer rates, dropped or duplicate packets, RTT, the number of bytes transferred, the estimated time left until completion, or to draw a completion bar.

Every field in the fc::TransferStats statistics object is documented. Note that some fields only apply to UDP-base file transfers. This is indicated in the documentation where appropriate.

More Examples

The installed documentation includes several more examples of simple applications making use of FC++. A link to the example code can be found in the "Start" menu.

Assuming a default installation, the examples are installed in "C:\Program Files\FCpp\doc\FCpp\examples\".

FCCL

Included as part of the FC++ API/SDK is fccl, a command-line tool that uses the FC++ API. This tool is very similar to the Java-based FileCatalyst command-line tool, with many of the same options. Using this tool, file transfers can easily be made from the command-line without having to install Java or any other dependencies on the client.

The FCCL tool and the FC++ SDK is currently available on the following platforms:

32-bit and 64-bit Windows
64-bit Mac
32-bit and 64-bit Linux
32-bit ARM7 Linux

Please ask if you need FC++ on a different platform. Any system with a modern C++11 compiler and the Boost C++ libraries should be capable of using FC++.

Table of Contents