#include <FCControl.hpp>

Public Member Functions
	Control (const fc::Options &options)
	Each fc::Control object represents a single FTP server connection to be controlled. More...

	Control (Control &&rhs)
	C++11 move constructor. More...

Control &	operator= (Control &&rhs)
	C++11 move assignment. More...

	~Control ()
	Destructing the fc::Control object terminates any connection to the ftp server. More...

bool	isValid () const
	Quickly determine if the fc::Control object is still valid, or if it has been gutted using either the C++11 move assignment or move constructor. More...

bool	isConnected () const
	Quickly determine if the fc::Control object is connected to a FTP server. More...

bool	isLoggedIn () const
	Quickly determine if the fc::Control object has completed the login process. More...

bool	isFileCatalystServer () const
	Quickly determine if the FTP server supports the FileCatalyst extensions. More...

std::string	getCurrentServerReplyString () const
	Quickly retrieve the last result string received from the FTP server. More...

fc::FtpServerReplyCodes	getCurrentServerReplyCode () const
	Quickly retrieve the most recent result code received from the FTP server. More...

const fc::GlobalStateAndStats &	getGlobalStateAndStats () const
	Get a reference to the global FC++ state and file transfer statistics for the control object. More...

fc::Control &	clearGlobalStats ()
	Clear all of the file transfer statistics. More...

fc::Control &	clearFileMap ()
	Clear the map of pending file transfers. More...

const fc::TransferStatsMap &	getFileMap () const
	Get a reference to the transfer file map. More...

size_t	getFileMapIndex () const
	Get the current transfer index into the file transfer mapping. More...

const fc::TransferStats &	getMostRecentFileStats () const
	Gets the most recent file transfer statistics. More...

Control &	connect ()
	Connect the fc::Control object to the specified FTP server. More...

Control &	disconnect ()
	Disconnect the fc::Control object from the FTP server. More...

const fc::Options &	getOptions () const
	Get the current set of options. More...

Control &	setNewOptions (const fc::Options &newOptions)
	Set new options. More...

std::string	getDirectoryListing (const fc::Remote &directory=fc::Remote(""))
	Get a directory listing from the FTP server. More...

std::string	getCurrentDirectory ()
	Get the current directory from the FTP server. More...

std::string	changeDirectory (const fc::Remote &directory)
	Change the working directory on the FTP server. More...

std::string	makeDirectory (const fc::Remote &directory)
	Create a new directory on the FTP server. More...

std::string	removeDirectory (const fc::Remote &directory)
	Remove an empty directory on the FTP server. More...

int	makeManyDirectories (const fc::StrVec &directories)
	Create multiple directories on the FTP server. More...

int	makeManyDirectories (const fc::Remote &directory)
	Create a directory for each element in the specified path. More...

fc::FDVec	getDirectoryDetails (const fc::Remote &directory=fc::Remote("."), const bool getMd5=false)
	Return as much information as possible on files and directories from the server. More...

Control &	prepareSingleFile (const fc::Remote &remote)
	Queue a single file for transfer. More...

Control &	prepareSingleFile (const fc::Local &local)
	Queue a single file for transfer. More...

Control &	prepareSingleFile (const fc::Remote &remote, const fc::Local &local)
	Queue a single file for transfer. More...

Control &	prepareSingleFile (const fc::Local &local, const fc::Remote &remote)
	Queue a single file for transfer. More...

Control &	prepareSingleFile (const char *const content, const size_t len, const fc::Remote &remote)
	Queue a single file for upload. More...

Control &	prepareRecursiveDir (const fc::Remote &remote, const fc::Local &local)
	Queue many files/directories for transfer. More...

Control &	prepareRecursiveDir (const fc::Local &local, const fc::Remote &remote)
	Queue many files/directories for transfer. More...

Control &	download ()
	Immediately download all files that have been queued for transfer. More...

Control &	upload ()
	Immediately upload all files that have been queued for transfer. More...

Control &	download (const fc::Remote &remote)
	Download a single file from the FTP server. More...

Control &	upload (const fc::Local &local)
	Upload a single file to the FTP server. More...

Control &	cancelTransfer ()
	Cancel the current file transfer (and all remaining files if multiple files have been prepared). More...

Control &	flush ()
	Flush the TCP control channel. More...

std::string	getFileMD5 (const fc::Local &local)
	Get the MD5 signature of the specified local file. More...

std::string	getFileMD5 (const fc::Remote &remote)
	Get the MD5 signature of the specified remote file. More...

std::string	getFileMD5 (const fc::Local &local, const int64_t offset, const int64_t chunkSize)
	Get the MD5 signature of a subsection of the specified local file. More...

std::string	getFileMD5 (const fc::Remote &remote, const int64_t offset, const int64_t chunkSize)
	Get the MD5 signature of a subsection of the specified remote file. More...

std::string	getFileModificationTime (const fc::Remote &remote)
	Get the modification timestamp of the specified remote file. More...

uint64_t	getFileSize (const fc::Local &local)
	Get the size of the specified remote file. More...

uint64_t	getFileSize (const fc::Remote &remote)
	Get the size of the specified remote file. More...

bool	nameExists (const fc::Local &local)
	Determine if a file or directory exists with the given name. More...

bool	nameExists (const fc::Remote &remote)
	Determine if a file or directory exists with the given name. More...

bool	nameDoesNotExist (const fc::Local &local)
	Determine if a file or directory already exists with this name. More...

bool	nameDoesNotExist (const fc::Remote &remote)
	Determine if a file or directory already exists with this name. More...

bool	isFile (const fc::Local &local)
	Determine if the specified name is a filename. More...

bool	isFile (const fc::Remote &remote)
	Determine if the specified name is a filename. More...

bool	isDirectory (const fc::Local &local)
	Determine if the specified name is a directory. More...

bool	isDirectory (const fc::Remote &remote)
	Determine if the specified name is a directory name. More...

Control &	deleteFile (const fc::Remote &remoteFile)
	Delete a remote file. More...

Control &	deleteFile (const fc::Local &localFile)
	Delete a local file. More...

std::string	renameFile (const fc::Remote &remoteFrom, const fc::Remote &remoteTo)
	Rename a remote file. More...

Control &	renameFile (const fc::Local &localFrom, const fc::Local &localTo)
	Rename a local file. More...

Control &	setStatsCallback (fc::StatisticsCallback callback, void *userCtx=NULL)
	Set a C-style callback function to be called once per second when file transfer statistics are updated. More...

Control &	noop ()
	Send a NO-OP to the server. More...

std::string	raw (const std::string &cmd, const fc::FtpServerReplyCodes expectedReply=fc::kOkay)
	Send an unmanaged raw command to the server. More...

fc::StrMap	getMap () const
	Get a map of all current settings and values. Used mostly for debug purpose. More...

Control &	getOptimalUnitAndBlockSizes (const uint64_t file_size_in_bytes, int &unit_size_in_bytes, int &block_size_in_bytes)
	Determine the best UDP unit and block sizes based on the given sizes. More...

uint64_t	detectApproximateUploadSpeed (const bool force_refresh=false)
	Get an approximation of the available upload transfer rate between the FC++ client and server. More...

uint64_t	detectApproximateDownloadSpeed (const bool force_refresh=false)
	Get an approximation of the available download transfer rate between the FC++ client and server. More...

Control &	deleteTemporaryFiles ()
	This is automatically called by FC++ to delete all temporary files once a transfer has completed. More...

Detailed Description

fc::Control is the client class C++ API used to control a FTP server and manage file transfers.

To transfer a file, it first needs to be added to the file map which is used to describe both the local and remote filename, as well as keep file transfer statistics. Once the file map exists, it can then be transferred using fc::Control::download() or fc::Control::upload().

The file map can be accessed using fc::Control::getGlobalStateAndStats() and can be completely reset using fc::Control::clearFileMap().

Note that multiple calls can be made to prepare...() to queue up many different files and directories, followed by a single call to download() or upload() to complete all of the queued transfers.

See also: fc::Control::prepareSingleFile(); fc::Control::prepareRecursiveDir()

Objects of type fc::Control (and fc::Options) may be accessed from different threads, but it becomes the caller's responsability to ensure thread safety. For example, don't attempt to run FTP commands (uploads, download, directory listings, etc) simultaneously with the same FC object from multiple threads.

Constructor & Destructor Documentation

◆ Control() [1/2]

fc::Control::Control ( const fc::Options & options )

Each fc::Control object represents a single FTP server connection to be controlled.

The fc::Control constructor makes a copy of the fc::Options parameter, so the lifetime of options passed in is irrelevant to the long-lived fc::Control objects. Also note that fc::Control is extremely small in size. The necessary memory is dynamically allocated from the heap so there should be no problem instantiating a fc::Control object on the stack.

For example:

fc::Options options;
options.setFtpServer( "192.168.6.75", 21 );
options.setUsernameAndPassword( "bob", "secret" );
options.setBandwidth( fc:Mbps(350), fc::Mbps(75) );
options.setMode( fc::kUdp );
fc::Control ftp( options );
ftp.connect();
ftp.upload( fc::Local( "backup.zip" ) );
ftp.download( fc::Remote( "client_list.txt" ) );
ftp.disconnect();

Warning: If fc::Control objects are created statically or on the heap, it is strongly recommended that they be destructed or disconnected with disconnect() before the application exits. Otherwise, if OpenSSL or Boost is de-initialized before fc::Control objects are destructed, this will cause problems (such as segfaults) when fc::Control attempts to disconnects once the objects go out of scope.; Similarly, creating a static fc::Control object at file scope can be a problem if Boost's static initialization has not yet happened. To prevent this problem, it is recommended that you allocate fc::Control objects on the stack, or use a function to return a static reference if a global-scope fc::Control object is absolutely necessary.

For example:

fc::Options get_ftp_options()
{
    fc::Options options( ... );
    options.setBandwidth( ... );
    options.setMd5Verification( ... );
    // ...
    return options;
}
 
fc::Control & get_ftp()
{
    // delay the construction of fc::Control so Boost's static initialization happens first
    static fc::Control ftp(get_ftp_options());
 
    if (ftp.isLoggedIn() == false)
    {
        ftp.connect();
        const fc::Remote dir("/backups/remote_office/daily");
        ftp.makeManyDirectories(dir);
        ftp.changeDirectory(dir);
    }
    return ftp;
}

Then in the rest of your code, you'd obtain a reference to that "global" FTP object:

// ...
fc::Control & ftp = get_ftp();
ftp.prepareSingleFile( ... );
ftp.prepareRecursiveDir( ... );
ftp.upload( ... );

See also: disconnect(); fc::Options

References Control().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Control() [2/2]

fc::Control::Control ( fc::Control && rhs )

C++11 move constructor.

The right-hand-side C++ object will be left in a gutted invalid state after the move. Do not attempt to re-use the original rhs object, otherwise a fc::Exception will be thrown.

References Control().

Here is the call graph for this function:

◆ ~Control()

fc::Control::~Control ( )

Destructing the fc::Control object terminates any connection to the ftp server.

Allowing a fc::Control object to go out-of-scope is the same as explicitely calling fc::Control::disconnect().

Member Function Documentation

◆ operator=()

fc::Control & fc::Control::operator= ( fc::Control && rhs )

C++11 move assignment.

The original lhs FTP Control object will be disconnected and deleted as part of the move.

The right-hand-side C++ object will be left in a gutted invalid state after the move. Do not attempt to re-use the original rhs object, otherwise a fc::Exception will be thrown.

◆ isValid()

bool fc::Control::isValid ( ) const

Quickly determine if the fc::Control object is still valid, or if it has been gutted using either the C++11 move assignment or move constructor.

Will return true if the object can still be used, or false if the internals of the object have been moved.

fc::Options my_options( ... );
fc::Control ftp_server_1( my_options );
bool is_valid = ftp_server_1.isValid(); // this returns "true"
 
fc::Control ftp_server_2( ftp_server_1 ); // move constructor
 
is_valid = ftp_server_1.isValid();      // this returns "false"
is_valid = ftp_server_2.isValid();      // this returns "true"

Note: This does not attempt to test the connection between the client and the FTP server.

See also: fc::Control::isConnected(); fc::Control::isLoggedIn(); fc::Control::noop()

Exceptions

n/a	This will return immmediately. It does not throw.

◆ isConnected()

bool fc::Control::isConnected ( ) const

Quickly determine if the fc::Control object is connected to a FTP server.

fc::Options options( ... );
fc::Control ftp( options );
 
// note that creating the ftp control object does not automatically or
// immediately connect to it, so calling isConnected() will return "false"
if (ftp.isConnected())
{
    ... // this will never run
}
 
// calling a method that needs the connection to be established, or explicitely
// calling fc::Control::connect() will cause the connection to be established
ftp.connect();
if (ftp.isConnected())
{
    ... // this code will run
}

Exceptions

n/a	This will return immmediately. It does not throw.

Here is the caller graph for this function:

◆ isLoggedIn()

bool fc::Control::isLoggedIn ( ) const

Quickly determine if the fc::Control object has completed the login process.

Internally, this also calls isConnected() prior to verifying if the ftp control object is logged in.

fc::Options options( ... );
fc::Control ftp( options );
 
// this next line will return "false" since creating the ftp control object does
// not automatically or immediately connect to it.
if (ftp.isLoggedIn())
{
    ... // this will never run
}
 
// calling a method that needs the connection to be established, or explicitely
// calling fc::Control::connect() will cause the connection to be established
ftp.connect();
if (ftp.isLoggedIn())
{
    ... // this code will run
}

Note: This is only accurate once fc::Control::isConnected() returns true.

Exceptions

n/a	This will return immmediately. It does not throw.

Here is the caller graph for this function:

◆ isFileCatalystServer()

bool fc::Control::isFileCatalystServer ( ) const

Quickly determine if the FTP server supports the FileCatalyst extensions.

Internally, this also calls isConnected() and isLoggedIn() prior to verifying if this is a FileCatalyst server.

fc::Options my_options( ... );
fc::Control ftp( my_options );
ftp.connect();
if ( ftp.isFileCatalystServer() )
{
    ... // this code will run only if the server is a FileCatalyst FTP server
}

Note: This is only accurate once fc::Control::isLoggedIn() returns true.

Exceptions

n/a	This will return immmediately. It does not throw.

Here is the caller graph for this function:

◆ getCurrentServerReplyString()

std::string fc::Control::getCurrentServerReplyString ( ) const

Quickly retrieve the last result string received from the FTP server.

For example:

getCurrentServerReplyString()	getCurrentServerReplyCode()
`"230 Login successful."`	fc::k230UserLoggedIn
`"250 Directory successfully changed."`	fc::k250RequestedActionOkay
`"226 Transfer complete"`	fc::k226ClosingDataConnectionTransferDone

Note: The FC++ library will throw fc::Exception when the result is unexpected after running commands on the FTP server, so normally there is no need to manually validate the server replies.

See also: fc::getTextFromServerReply(); fc::Control::getCurrentServerReplyCode()

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ getCurrentServerReplyCode()

fc::FtpServerReplyCodes fc::Control::getCurrentServerReplyCode ( ) const

Quickly retrieve the most recent result code received from the FTP server.

For example:

getCurrentServerReplyString()	getCurrentServerReplyCode()
`"230 Login successful."`	fc::k230UserLoggedIn
`"250 Directory successfully changed."`	fc::k250RequestedActionOkay
`"226 Transfer complete"`	fc::k226ClosingDataConnectionTransferDone

Note: The FC++ library will throw fc::Exception when the result is unexpected after running commands on the FTP server, so normally there is no need to manually validate the server replies.

See also: fc::FtpServerReplyCodes; fc::getCodeFromServerReply(); fc::Control::getCurrentServerReplyString()

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ getGlobalStateAndStats()

const fc::GlobalStateAndStats & fc::Control::getGlobalStateAndStats ( ) const

Get a reference to the global FC++ state and file transfer statistics for the control object.

ftp.prepareRecursiveDir(...);
ftp.upload();
 
// make a local copy of the transfer statistics
fc::GlobalStateAndStats all_transfer_information = ftp.getGlobalStateAndStats();
 
// possibly do something with the global transfer statistics
do_something( all_transfer_information.stats );
 
for ( const fc::TransferStats &individual_file_stats : all_transfer_information.fileStatsMap )
{
    do_something( individual_file_stats);   // possibly display or log the individual file statistics
}

See also: fc::GlobalStats (a brief summary of transfer statistics); fc::TransferStatsMap (a std::map of fc::TransferStats, one for each file transferred); fc::GlobalStateAndStats (contains a fc::GlobalStats and a fc::TransferStatsMap)

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ clearGlobalStats()

fc::Control & fc::Control::clearGlobalStats ( )

Clear all of the file transfer statistics.

For example, the stats for fc::GlobalStats::totalNumberOfFilesSent and fc::GlobalStats::totalNumberOfFilesReceived could be non-zero after a number of files have been sent. But calling this would reset those global stats to zero:

fc::Control ftp( my_options );
ftp.upload( fc::Local( "test.txt" ) );
ftp.download( fc::Remote( "backup.zip" ) );
ftp.clearGlobalStats();

See also: fc::GlobalStats

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ clearFileMap()

fc::Control & fc::Control::clearFileMap ( )

Clear the map of pending file transfers.

If you are re-using a fc::Control object for multiple transfers, you'll want to clear the file map between transfers to prevent the same files from being transferred multiple times.

Warning: The file map is also where the individual file statistics are stored after uploads and downloads. If you need to retain the file statistics, make sure you copy them prior to clearing the file map.

// this might queue up many files and subdirectories to transfer
ftp.prepareRecursiveDir(...);
ftp.upload(); // or ftp.download()
 
... // do something here with the file map stats, possibly display or log them to a file
 
// before preparing more files for transfer, clear out the previous file map and statistics
ftp.clearFileMap();
 
// we can then proceed to queue up new files or directories again
ftp.prepareSingleFile(...);

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

Here is the caller graph for this function:

◆ getFileMap()

const fc::TransferStatsMap & fc::Control::getFileMap ( ) const

Get a reference to the transfer file map.

This is the same as calling getGlobalStateAndStats() and dereferencing fileStatsMap.

ftp.prepareRecursiveDir(...);
ftp.upload();
 
// make a local copy of the individual file transfer information
fc::TransferStatsMap file_stats = ftp.getFileMap();
 
for ( const fc::TransferStats &individual_file_stats : file_stats )
{
    do_something( individual_file_stats );  // possibly display or log the file statistics
}

See also: fc::GlobalStateAndStats::fileStatsMap; fc::TransferStatsMap

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

Here is the caller graph for this function:

◆ getFileMapIndex()

size_t fc::Control::getFileMapIndex ( ) const

Get the current transfer index into the file transfer mapping.

The first file transfer starts at index '1' and each additional file queued increments the index sequentially.

See also: fc::Control::clearFileMap(); fc::GlobalStateAndStats::fileStatsIdx

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ getMostRecentFileStats()

const fc::TransferStats & fc::Control::getMostRecentFileStats ( ) const

Gets the most recent file transfer statistics.

This is the same as getting the entire file transfer map and indexing into it using the file map index.

See also: fc::Control::getFileMap(); fc::Control::getFileMapIndex()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the transfer file map is empty.

References FC_WHERE.

Here is the caller graph for this function:

◆ connect()

fc::Control & fc::Control::connect ( )

Connect the fc::Control object to the specified FTP server.

Will return once the connect and login process have finished.

Note: Explicitely calling this is not required, since a connection will automatically be established once an API call is made that requires an open connection to the server.

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if a connection to the server has already been established.
fc::Exception	if boost::asio returned an error establishing the SSL control channel connection to the server.
fc::Exception	if boost::asio returned an error performing the SSL handshake on the control channel connection.
fc::Exception	if boost::asio returned an error establishing a non-encrypted TCP control channel connection to the server.
fc::Exception	if the server didn't send anything to read on the non-encrypted TCP control channel.
fc::Exception	if the server response is unexpected.
fc::Exception	if a user has already logged in.

References FC_WHERE.

Here is the caller graph for this function:

◆ disconnect()

fc::Control & fc::Control::disconnect ( )

Disconnect the fc::Control object from the FTP server.

This is automatically called when a fc::Control object goes out of scope.

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

Here is the caller graph for this function:

◆ getOptions()

const fc::Options & fc::Control::getOptions ( ) const

Get the current set of options.

This can be used to modify the existing set of options.

fc::Options options = ftp.getOptions();
options.setMode( fc::kUdp );
options.setLimits( 1200 );
ftp.setNewOptions( options );

See also: fc::Control::setNewOptions()

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ setNewOptions()

fc::Control & fc::Control::setNewOptions ( const fc::Options & newOptions )

Set new options.

Note: Several options only take effect after fc::Control::disconnect() is called and a new connection is established.

fc::Options options = ftp.getOptions();
options.setMode( fc::kUdp );
options.setLimits( 1200 );
ftp.setNewOptions( options );

Warning

If the new options causes a change to any of the following values, any existing connection to the FTP server will be dropped:

The server's hostname or IP address.
The server's TCP port.
The username used for login.
The password used for login.

See also: fc::Control::getOptions()

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

Here is the caller graph for this function:

◆ getDirectoryListing()

std::string fc::Control::getDirectoryListing ( const fc::Remote & directory = fc::Remote("") )

Get a directory listing from the FTP server.

The format of the string depends on the type of FTP server. FC++ makes no attempt to parse the directory listing.

Calling fc::Control::getDirectoryDetails() may be preferable as FC++ then attempts to automatically parse the results and stores the details in a std::vector.

fc::Options options( ... );
fc::Control ftp( options );
 
std::cout << ftp.getDirectoryListing( fc::Remote( "/pub/incoming" ) << std::endl;

See also: fc::Control::getDirectoryDetails(); fc::Control::nameExists(); fc::Control::isDirectory(); fc::Control::isFile()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

Here is the caller graph for this function:

◆ getCurrentDirectory()

std::string fc::Control::getCurrentDirectory ( )

Get the current directory from the FTP server.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.changeDirectory( fc::Remote( "/pub/incoming" );
std::cout << ftp.getCurrentDirectory() << std::endl;

See also: fc::Control::changeDirectory()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

Here is the caller graph for this function:

◆ changeDirectory()

std::string fc::Control::changeDirectory ( const fc::Remote & directory )

Change the working directory on the FTP server.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.changeDirectory( fc::Remote( "/pub/incoming" );
std::cout << ftp.getCurrentDirectory() << std::endl;

See also: fc::Control::getCurrentDirectory()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

Here is the caller graph for this function:

◆ makeDirectory()

std::string fc::Control::makeDirectory ( const fc::Remote & directory )

Create a new directory on the FTP server.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.makeDirectory  ( fc::Remote( "/tmp/testing" );
ftp.changeDirectory( fc::Remote( "/tmp/testing" );
ftp.makeDirectory  ( fc::Remote( "relative_dir" );  // this creates /tmp/testing/relative_dir/

See also: fc::Control::makeManyDirectories(); fc::Control::removeDirectory()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

Here is the caller graph for this function:

◆ removeDirectory()

std::string fc::Control::removeDirectory ( const fc::Remote & directory )

Remove an empty directory on the FTP server.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.makeDirectory  ( fc::Remote( "/tmp/testing" );
ftp.removeDirectory( fc::Remote( "/tmp/testing" );

See also: fc::Control::makeDirectory()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

Here is the caller graph for this function:

◆ makeManyDirectories() [1/2]

int fc::Control::makeManyDirectories ( const fc::StrVec & directories )

Create multiple directories on the FTP server.

Sometimes making a single directory at a time is inconvenient. Given a vector of directory entries, go through each one and create all the directory components on the remote FC server.

For example:

fc::Options options( ... );
fc::Control ftp( options );
 
fc::StrVec v;
v.push_back( "/projectA/testing/output" );
v.push_back( "/projectA/bin/debug"      );
ftp.makeManyDirectories( v );

The previous code example will ensure the following five directories are created on the server without throwing an exception for directories that already exist:

 /projectA
 /projectA/testing
 /projectA/testing/output
 /projectA/bin
 /projectA/bin/debug

See also: fc::Control::makeDirectory()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ makeManyDirectories() [2/2]

int fc::Control::makeManyDirectories ( const fc::Remote & directory )

Create a directory for each element in the specified path.

For example:

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.makeManyDirectories( "/project/tmp/uploaded/draft" );

The previous code example will ensure the following 4 directories are created if they don't already exist:

 /project
 /project/tmp
 /project/tmp/uploaded
 /project/tmp/uploaded/draft

See also: fc::Control::makeDirectory()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ getDirectoryDetails()

fc::FDVec fc::Control::getDirectoryDetails	(	const fc::Remote &	directory = `fc::Remote(".")`,
		const bool	getMd5 = `false`
	)

Return as much information as possible on files and directories from the server.

This parses the server's directory information, while fc::Control::getDirectoryListing() returns a plain text string which FC++ does not attempt to parse.

This returns a std::vector of fc::FileDetails, which contains details such as file size, last modified timestamp, md5 checksum, and group/owner details when available.

Warning: The MD5 checksum can be expensive to run on very large files or on directories with many files. Set getMd5 to false to disable retrieving the md5 checksum of each file.

fc::Options options( ... );
fc::Control ftp( options );
 
fc::FDVec v = ftp.getDirectoryDetails( "/project/docs", true );
for ( const fc::FileDetails &file : v )
{
    std::cout   << file.filename << ": "
                << fc::formatBytesSI( file.filesize ) << ": "
                << file.md5
                << std::endl;
}

Note: Some servers skip the directory names and only return the filenames, in which case getDirectoryListing() may be preferred.

See also: fc::Control::getDirectoryListing(); fc::Control::nameExists(); fc::Control::isDirectory(); fc::Control::isFile(); fc::FileDetails; fc::FDVec

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

Here is the caller graph for this function:

◆ prepareSingleFile() [1/5]

fc::Control & fc::Control::prepareSingleFile ( const fc::Remote & remote )

Queue a single file for transfer.

This can be called multiple times or combined with prepareRecursiveDir() to queue many files.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.prepareSingleFile( fc::Remote( "readme.txt" ) );
ftp.prepareSingleFile( fc::Remote( "listing.txt" ) );
ftp.download();

See also: fc::Remote; fc::Control::clearFileMap()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the remote filename is empty.

References FC_WHERE.

Here is the caller graph for this function:

◆ prepareSingleFile() [2/5]

fc::Control & fc::Control::prepareSingleFile ( const fc::Local & local )

Queue a single file for transfer.

This can be called multiple times or combined with prepareRecursiveDir() to queue many files.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.prepareSingleFile( fc::Local( "c:\tmp\backup1.zip" ) );
ftp.prepareSingleFile( fc::Local( "c:\tmp\backup2.zip" ) );
ftp.upload();

See also: fc::Local; fc::Control::clearFileMap()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the local filename is empty.

References FC_WHERE.

◆ prepareSingleFile() [3/5]

fc::Control & fc::Control::prepareSingleFile	(	const fc::Remote &	remote,
		const fc::Local &	local
	)

Queue a single file for transfer.

This provides both the remote and local filenames in case a file needs to be renamed as part of the transfer.

This can be called multiple times or combined with prepareRecursiveDir() to queue many files.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.prepareSingleFile( fc::Remote( "readme.txt" ), fc::Local( "readme_file_from_ftp_server.txt" ) );
ftp.download();

Due to method overloading, the order in which the local and remote names are provided do not matter. The same code could have been written as:

ftp.prepareSingleFile( fc::Local( "readme_file_from_ftp_server.txt" ), fc::Remote( "readme.txt" ) );

ftp.download();

See also: fc::Local; fc::Remote; fc::Control::clearFileMap()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the remote filename is empty.
fc::Exception	if the local filename is empty.

References FC_WHERE.

◆ prepareSingleFile() [4/5]

fc::Control & fc::Control::prepareSingleFile	(	const fc::Local &	local,
		const fc::Remote &	remote
	)

Queue a single file for transfer.

This provides both the local and remote filenames in case a file needs to be renamed as part of the transfer.

This can be called multiple times or combined with prepareRecursiveDir() to queue many files.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.prepareSingleFile( fc::Local( "readme_file_from_ftp_server.txt" ), fc::Remote( "readme.txt" ) );
ftp.download();

Due to method overloading, the order in which the local and remote names are provided do not matter. The same code could have been written as:

ftp.prepareSingleFile( fc::Remote( "readme.txt" ), fc::Local( "readme_file_from_ftp_server.txt" ) );

ftp.download();

See also: fc::Local; fc::Remote; fc::Control::clearFileMap()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the local filename is empty.
fc::Exception	if the remote filename is empty.

References FC_WHERE.

◆ prepareSingleFile() [5/5]

fc::Control & fc::Control::prepareSingleFile	(	const char *const	content,
		const size_t	len,
		const fc::Remote &	remote
	)

Queue a single file for upload.

The content (instead of a filename) is provided to FC++ and temporarily written to disk locally via std::tmpnam() prior to this call returning. This means that content can be freed, re-used, or allowed to go out of scope as soon as this call to prepareSingleFile() has completed.

It is perfectly valid to make multiple calls to prepareSingleFile() prior to calling upload().

fc::Options options( ... );
fc::Control ftp( options );
 
const std::string content1 = "Hello, world!";
const std::string content2 = "this is just a test";
 
ftp.prepareSingleFile( content1.c_str(), content1.size(), fc::Remote("example.txt") );
ftp.prepareSingleFile( content2.c_str(), content2.size(), fc::Remote("readme.txt") );
 
ftp.upload();

Note: File transfers prepared this way are only good for uploading from the client to the server.; Any temporary files created during the upload are automatically deleted by FC++ once the transfer has finished.

See also: deleteTemporaryFiles()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the contents of the file to upload cannot be saved to a temporary file.

References FC_WHERE.

◆ prepareRecursiveDir() [1/2]

fc::Control & fc::Control::prepareRecursiveDir	(	const fc::Remote &	remote,
		const fc::Local &	local
	)

Queue many files/directories for transfer.

This will connect to the server and recursively obtain directory listings starting with remote. All files found will be queued for transfer into the specified local directory. The remote directory structure will be re-created locally.

This can be called multiple times or combined with prepareSingleFile() to queue many files.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.prepareRecursiveDir ( fc::Remote( "ready_for_download"  ), fc::Local( "downloads"               ) );
ftp.prepareSingleFile   ( fc::Remote( "listing.txt"         ), fc::Local( "downloads/output.txt"    ) );
 
ftp.download();

See also: fc::Local; fc::Remote; fc::Control::prepareSingleFile(); fc::Control::clearFileMap()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the remote directory name is empty.
fc::Exception	if the local directory name is empty.

References FC_WHERE.

Here is the caller graph for this function:

◆ prepareRecursiveDir() [2/2]

fc::Control & fc::Control::prepareRecursiveDir	(	const fc::Local &	local,
		const fc::Remote &	remote
	)

Queue many files/directories for transfer.

This will recursively obtain directory listings starting with local. All files found will be queued for transfer into the specified remote directory. The local directory structure will be re-create on the remote server.

This can be called multiple times or combined with prepareSingleFile() to queue many files.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.prepareRecursiveDir ( fc::Local( "c:\data"              ), fc::Remote( "/var/www/htdocs/data"       ) );
ftp.prepareSingleFile   ( fc::Local( "c:\stuff\index.txt"   ), fc::Remote( "/var/www/htdocs/index.html" ) );
 
ftp.upload();

See also: fc::Local; fc::Remote; fc::Control::prepareSingleFile(); fc::Control::clearFileMap()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the local directory name is empty.
fc::Exception	if the remote directory name is empty.

References FC_WHERE.

◆ download() [1/2]

fc::Control & fc::Control::download ( )

Immediately download all files that have been queued for transfer.

This will only return once the transfers have completed.

If a single file was downloaded, the corresponding statistics can be obtained via fc::Control::getMostRecentFileStats(). Otherwise, if multiple files were downloaded, the statistics can be obtained using fc::Control::getGlobalStateAndStats().

See also: fc::Control::clearFileMap(); fc::Control::prepareSingleFile(); fc::Control::prepareRecursiveDir()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if a file failed to download.

References FC_WHERE, fc::formatTimeDuration(), and fc::k550RequestAbortedFileOrDirectoryError.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ upload() [1/2]

fc::Control & fc::Control::upload ( )

Immediately upload all files that have been queued for transfer.

This will only return once the transfers have completed.

If a single file was uploaded, the corresponding statistics can be obtained via fc::Control::getMostRecentFileStats(). Otherwise, if multiple files were uploaded, the statistics can be obtained using fc::Control::getGlobalStateAndStats().

See also: fc::Control::clearFileMap(); fc::Control::prepareSingleFile(); fc::Control::prepareRecursiveDir()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if a file failed to upload.

References FC_WHERE, fc::formatTimeDuration(), fc::k550RequestAbortedFileOrDirectoryError, and fc::Exception::text.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ download() [2/2]

fc::Control & fc::Control::download ( const fc::Remote & remote )

Download a single file from the FTP server.

For very simple single file transfers, the clear + prepare + download calls have been combined into a single FC++ API.

fc::Options options( ... );
fc::Control ftp( options );
ftp.download( fc::Remote( "readme.txt" ) );

This is equivalent to:

fc::Options options( ... );
fc::Control ftp( options );
ftp.clearFileMap();
ftp.prepareSingleFile( fc::Remote( "readme.txt" ) );
ftp.download();

Note: This will automatically clear any existing file mapping. Any files transferred using this method will be saved in the default directories as defined in fc::Options used in fc::Control::Control( const fc::Options &options ) or in fc::Control::setNewOptions().

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the remote filename is empty.
fc::Exception	if the file failed to download.

References FC_WHERE.

◆ upload() [2/2]

fc::Control & fc::Control::upload ( const fc::Local & local )

Upload a single file to the FTP server.

For very simple single file transfers, the clear + prepare + upload calls have been combined into a single FC++ API.

fc::Options options( ... );
fc::Control ftp( options );
ftp.upload( fc::Local( "backup.zip" ) );

This is equivalent to:

fc::Options options( ... );
fc::Control ftp( options );
ftp.clearFileMap();
ftp.prepareSingleFile( fc::Local( "backup.zip" ) );
ftp.upload();

Note: This will automatically clear any existing file mapping. Any files transferred using this method will be saved in the default directories as defined in fc::Options used in fc::Control::Control( const fc::Options &options ) or in fc::Control::setNewOptions().

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the local filename is empty.
fc::Exception	if the file failed to upload.

References FC_WHERE.

◆ cancelTransfer()

fc::Control & fc::Control::cancelTransfer ( )

Cancel the current file transfer (and all remaining files if multiple files have been prepared).

Since download() and upload() are synchronous, this only makes sense to be called from a secondary thread while a transfer is in progress.

Calling cancelTransfer() inserts an asynchronous ABOR into the TCP control channel, and does not wait for a reply from the server before returning. It is permissible to call this multiple times, but also see flush().

Note

FC++ can cancel the following file transfers:

UDP upload
UDP download
TCP (aka FTP) upload

Cancelling TCP downloads is not supported by FC servers.

See also: flush()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ flush()

fc::Control & fc::Control::flush ( )

Flush the TCP control channel.

If there is the possiblity that cancelTransfer() was called on a secondary thread to cancel a previous file transfer, it may be necessary to flush the TCP control stream before the FTP control object can be re-used to initiate a new file transfer.

This will cause the FC++ library to briefly pause and re-sync with the FTP server, flushing any pending replies from the TCP control channel that may result from having sent ABOR asynchronously while another command was running.

The flush() method would be called from the same thread that attempted the upload or download, not from the thread that posted the asynchronous ABOR. Here is a simple scenario:

// Thread 1 is the main thread of the application, and runs the GUI.
// Thread 2 runs the uploads and downloads.  Because FC++ is
// synchronous when it does uploads and downloads, it would lock
// up the GUI for long periods of time while transfering files,
// so it runs on thread 2.
fc::Options options( ... );
fc::Control ftp( options );
bool cancel_requested = false;

// In thread 1, the user clicks on a "Cancel" pushbutton.
ftp.cancelTransfer(); // returns immediately, does not wait for a server reply
cancel_requested = true;

// Meanwhile, thread 2 is busy downloading a file.  The
// fc::Control object notices cancel has been requested, and
// stops the transfer.  The server will also notice the ABOR
// that was inserted into the middle of the TCP control channel.
// There may also have been multiple calls from thread 1 to
// cancelTransfer() if the user clicked on the "Cancel" button
// many times.  And the server may have had time to send out the
// entire file, even though FC++ running on thread 2 was told to
// cancel before the entire file was received.  This is where
// and why flush() needs to be called on thread 2.
ftp.download( ... );
if (cancel_requested)
{
    ftp.flush(); // re-sync FC++ with the server
}

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the TCP control channel failed to flush.

References FC_WHERE.

◆ getFileMD5() [1/4]

std::string fc::Control::getFileMD5 ( const fc::Local & local )

Get the MD5 signature of the specified local file.

fc::Options options( ... );
fc::Control ftp( options );
 
std::cout << ftp.getFileMD5( fc::Local( "c:\temp\backup.zip" ) ) << std::endl;

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

Here is the caller graph for this function:

◆ getFileMD5() [2/4]

std::string fc::Control::getFileMD5 ( const fc::Remote & remote )

Get the MD5 signature of the specified remote file.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.changeDirectory( "old_files" );
std::cout << ftp.getFileMD5( fc::Remote( "backup.tgz" ) ) << std::endl;

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ getFileMD5() [3/4]

std::string fc::Control::getFileMD5	(	const fc::Local &	local,
		const int64_t	offset,
		const int64_t	chunkSize
	)

Get the MD5 signature of a subsection of the specified local file.

FC++ uses this internally when attempting to resume a previously interrupted file transfer.

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the offset is invalid.

References FC_WHERE.

◆ getFileMD5() [4/4]

std::string fc::Control::getFileMD5	(	const fc::Remote &	remote,
		const int64_t	offset,
		const int64_t	chunkSize
	)

Get the MD5 signature of a subsection of the specified remote file.

FC++ uses this internally when attempting to resume a previously interrupted file transfer.

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the offset is invalid.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ getFileModificationTime()

std::string fc::Control::getFileModificationTime ( const fc::Remote & remote )

Get the modification timestamp of the specified remote file.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.changeDirectory( "old_files" );
std::cout << ftp.getFileModificationTime( fc::Remote( "backup.tgz" ) ) << std::endl;

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

Here is the caller graph for this function:

◆ getFileSize() [1/2]

uint64_t fc::Control::getFileSize ( const fc::Local & local )

Get the size of the specified remote file.

fc::Options options( ... );
fc::Control ftp( options );
 
uint64_t filesize = ftp.getFileSize( fc::Local( "c:\temp\backup.zip" ) );
std::cout << fc::formatBytesIEC( filesize ) << std::endl;

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the local file size cannot be determined.

References FC_WHERE.

Here is the caller graph for this function:

◆ getFileSize() [2/2]

uint64_t fc::Control::getFileSize ( const fc::Remote & remote )

Get the size of the specified remote file.

fc::Options options( ... );
fc::Control ftp( options );
 
uint64_t filesize = ftp.getFileSize( fc::Remote( "backup.tgz" ) );
std::cout << fc::formatBytesIEC( filesize ) << std::endl;

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ nameExists() [1/2]

bool fc::Control::nameExists ( const fc::Local & local )

Determine if a file or directory exists with the given name.

Returns: TRUE if a file or directory already exists with this name.

fc::Options options( ... );
fc::Control ftp( options );
if ( ftp.nameExists( fc::Local( "backup" ) ) )
{
    ...
}

See also: nameDoesNotExist()

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

Here is the caller graph for this function:

◆ nameExists() [2/2]

bool fc::Control::nameExists ( const fc::Remote & remote )

Determine if a file or directory exists with the given name.

Returns: TRUE if a file or directory already exists with this name.

fc::Options options( ... );
fc::Control ftp( options );
if ( ftp.nameExists( fc::Remote( "backup.zip" ) ) )
{
    ...
}

See also: nameDoesNotExist()

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ nameDoesNotExist() [1/2]

bool fc::Control::nameDoesNotExist ( const fc::Local & local )

inline

Determine if a file or directory already exists with this name.

Returns: TRUE if nothing exists with the given name.

fc::Options options( ... );
fc::Control ftp( options );
if ( ftp.nameDoesNotExist( fc::Local( "backup" ) ) )
{
    ...
}

See also: nameExists()

References nameExists().

Here is the call graph for this function:

◆ nameDoesNotExist() [2/2]

bool fc::Control::nameDoesNotExist ( const fc::Remote & remote )

inline

Determine if a file or directory already exists with this name.

Returns: TRUE if nothing exists with the given name.

fc::Options options( ... );
fc::Control ftp( options );
if ( ftp.nameDoesNotExist( fc::Remote( "backup.zip" ) ) )
{
    ...
}

See also: nameExists()

References nameExists().

Here is the call graph for this function:

◆ isFile() [1/2]

bool fc::Control::isFile ( const fc::Local & local )

Determine if the specified name is a filename.

fc::Options options( ... );
fc::Control ftp( options );
if ( ftp.isFile( fc::Local( "backup" ) ) )
{
    ...
}

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ isFile() [2/2]

bool fc::Control::isFile ( const fc::Remote & remote )

Determine if the specified name is a filename.

Note: The logic to determine if the given name is a file includes obtaining the list of file names in the parent directory and looking for the requested file. This will be a performance bottleneck if it has to be repeated many times in a loop, or if the parent directory contains a large number of files.

fc::Options options( ... );
fc::Control ftp( options );
if ( ftp.isFile( fc::Remote( "client_list" ) ) )
{
    ...
}

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ isDirectory() [1/2]

bool fc::Control::isDirectory ( const fc::Local & local )

Determine if the specified name is a directory.

fc::Options options( ... );
fc::Control ftp( options );
if ( ftp.isDirectory( fc::Local( "backup" ) ) )
{
    ...
}

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ isDirectory() [2/2]

bool fc::Control::isDirectory ( const fc::Remote & remote )

Determine if the specified name is a directory name.

Note: the isDirectory() functionality makes use of isFile() internally, and thus is subject to the same performance penalty when called repeatedly in a loop, or when the parent directory contains a large number of files. See isFile() for details.

fc::Options options( ... );
fc::Control ftp( options );
if ( ftp.isDirectory( fc::Remote( "incoming" ) ) )
{
    ...
}

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ deleteFile() [1/2]

fc::Control & fc::Control::deleteFile ( const fc::Remote & remoteFile )

Delete a remote file.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.deleteFile( fc::Remote( "old_backup.zip" ) );

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ deleteFile() [2/2]

fc::Control & fc::Control::deleteFile ( const fc::Local & localFile )

Delete a local file.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.deleteFile( fc::Local( "old_image.iso" ) );

Exceptions

fc::Exception if the file cannot be deleted.

References FC_WHERE, and fc::Name::full().

Here is the call graph for this function:

◆ renameFile() [1/2]

std::string fc::Control::renameFile	(	const fc::Remote &	remoteFrom,
		const fc::Remote &	remoteTo
	)

Rename a remote file.

fc::Options options( ... );
fc::Control ftp( options );
 
ftp.renameFile( fc::Remote( "readme.txt" ), fc::Remote( "readme.old" ) );

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ renameFile() [2/2]

fc::Control & fc::Control::renameFile	(	const fc::Local &	localFrom,
		const fc::Local &	localTo
	)

Rename a local file.

ftp.renameFile( fc::Local( "readme.txt" ), fc::Local( "readme.old" ) );

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the file cannot be renamed.

References FC_WHERE.

◆ setStatsCallback()

fc::Control & fc::Control::setStatsCallback	(	fc::StatisticsCallback	callback,
		void *	userCtx = `NULL`
	)

Set a C-style callback function to be called once per second when file transfer statistics are updated.

A single statistics callback is maintained by FC++, optionally with a user-supplied void * pointer that can be used to track context. Only a single callback function is supported. Specifying a 2nd callback erases the first one.

See also: Additional details and code examples in fc::StatisticsCallback.

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

Here is the caller graph for this function:

◆ noop()

fc::Control & fc::Control::noop ( )

Send a NO-OP to the server.

Can be useful to confirm the control object is still connected to the FTP server.

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if boost::asio returned an error while sending the command to the server.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ raw()

std::string fc::Control::raw	(	const std::string &	cmd,
		const fc::FtpServerReplyCodes	expectedReply = `fc::kOkay`
	)

Send an unmanaged raw command to the server.

Warning: This is normally not needed and use is strongly discouraged.

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server response is unexpected.

Returns: fc::Control::getCurrentServerReplyString()

References FC_WHERE.

◆ getMap()

fc::StrMap fc::Control::getMap ( ) const

Get a map of all current settings and values. Used mostly for debug purpose.

Exceptions

fc::Exception if this method is called on a C++ object that has been moved and is no longer valid internally.

References FC_WHERE.

◆ getOptimalUnitAndBlockSizes()

fc::Control & fc::Control::getOptimalUnitAndBlockSizes	(	const uint64_t	file_size_in_bytes,
		int &	unit_size_in_bytes,
		int &	block_size_in_bytes
	)

Determine the best UDP unit and block sizes based on the given sizes.

This is normally handled automatically by FC++ when sending or receiving files via UDP.

Parameters

[in]	file_size_in_bytes	Size of the file to be sent or received via UDP.
[in,out]	unit_size_in_bytes	On input, this is the maximum unit size to use. The unit size must be less than the block size. On output, this is set to the best unit size given the file size.
[in,out]	block_size_in_bytes	On input, this is the maximum block size to use. On output, this is set to the best block size given the file size.

Note: If either the given unit_size_in_bytes or block_size_in_bytes is set to zero or to an invalid value, then the limits from the ftp control object's fc::Options will be used.

See also: fc::Options::setLimits()

For example, this uses a 1 KiB unit size and 2 MiB block size as maximum values to determine the optimal unit and block when transferring a 123,456-byte file over UDP:

fc::Options options;
options.setLimits( 1024, 2097152 );
fc::Control ftp(options);
 
int unit_size  = 0;
int block_size = 0;
 
ftp.getOptimalUnitAndBlockSizes( 123456, unit_size, block_size );
std::cout << "unit size:  " << fc::formatBytesIEC(unit_size)  << std::endl;
std::cout << "block size: " << fc::formatBytesIEC(block_size) << std::endl;

In this next example, the unit and block sizes in fc::Control are ignored, and instead a maximum value is specified for both the unit and block sizes:

fc::Options options;
options.setLimits( 1024, 4194304 );
fc::Control ftp(options);
 
int unit_size  = 1200;
int block_size = 7654321;
 
ftp.getOptimalUnitAndBlockSizes( 123456789, unit_size, block_size );
std::cout << "unit size:  " << fc::formatBytesIEC(unit_size)  << std::endl;
std::cout << "block size: " << fc::formatBytesIEC(block_size) << std::endl;

Note: Calling fc::Control::getOptimalUnitAndBlockSizes() does not modify the limits used by the FTP fc::Control object! Normally the fc::Control object will automatically choose the best unit and block sizes as each file is transfered. If you wish to modify these limits, you must explicitely set them in fc::Options prior to uploading or downloading a file:
fc::Options options = ftp.getOptions();

options.setLimits( 1024, 123456789 );

ftp.setNewOptions( options );

ftp.upload( ... );

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the file block size, the packet unit size, or the buffer size are smaller than expected.

References FC_WHERE, stats, and fc::TransferStats::unitSize.

◆ detectApproximateUploadSpeed()

uint64_t fc::Control::detectApproximateUploadSpeed ( const bool force_refresh = false )

Get an approximation of the available upload transfer rate between the FC++ client and server.

The rate returned is in bps, and requires the use of UDP data transfers.

FC++ keeps different values for both upload and download in case of asymetrical links.

Parameters

[in] force_refresh Upload and download bandwidth detection normally runs only once in each direction. The results are then cached within the fc::Control object. Set force_refresh to true to force FC++ to ignore any previous cached values and re-calculate a new transfer rate.

For example, a download rate and 1/2 speed slow start can be explicitely queried and set like this:

fc::Options options( ... );
fc::Control ftp( options );
ftp.connect();
const uint64_t rate = ftp.detectApproximateDownloadSpeed(true);
std::cout << "setting the transfer rate to " << fc::formatTransferRate(rate) << std::endl;
options.setBandwidth( rate, rate / 2 );
ftp.setNewOptions( options );

Similar behaviour can be triggered by setting a bandwidth rate of zero (which is the default). When set to zero, FC++ knows to automatically determine a reasonable transfer rate to use by internally making identical calls to fc::Control::detectApproximateUploadSpeed() or fc::Control::detectApproximateDownloadSpeed():

fc::Options options( ... );
options.setBandwidth( 0 ); // or:  options.setBandwidth( fc::kZero_bps );
fc::Control ftp( options );
ftp.connect();

Note: You may want to enable congestion control to automatically detect when the available link increases or decreases due to other network traffic. Congestion control will continuously make the necessary adjustments to the rate as the transfer progresses.

See also: fc::Options::setCongestionControl(); fc::Options::setBandwidth(); fc::formatTransferRate()

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server is not licensed for UDP.
fc::Exception	if the server is a traditional (non-FileCatalyst) FTP server.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ detectApproximateDownloadSpeed()

uint64_t fc::Control::detectApproximateDownloadSpeed ( const bool force_refresh = false )

Get an approximation of the available download transfer rate between the FC++ client and server.

The rate returned is in bps. See fc::Control::detectApproximateUploadSpeed() for documentation.

Exceptions

fc::Exception	if this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exception	if the server is not licensed for UDP.
fc::Exception	if the server is a traditional (non-FileCatalyst) FTP server.
fc::Exception	if the server response is unexpected.

References FC_WHERE.

◆ deleteTemporaryFiles()

fc::Control & fc::Control::deleteTemporaryFiles ( )

This is automatically called by FC++ to delete all temporary files once a transfer has completed.

The documentation for this class was generated from the following files:

src/publicInclude/FCControl.hpp
src/libfc/FCControl.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Control() [1/2]

◆ Control() [2/2]

◆ ~Control()

Member Function Documentation

◆ operator=()

◆ isValid()

◆ isConnected()

◆ isLoggedIn()

◆ isFileCatalystServer()

◆ getCurrentServerReplyString()

◆ getCurrentServerReplyCode()

◆ getGlobalStateAndStats()

◆ clearGlobalStats()

◆ clearFileMap()

◆ getFileMap()

◆ getFileMapIndex()

◆ getMostRecentFileStats()

◆ connect()

◆ disconnect()

◆ getOptions()

◆ setNewOptions()

◆ getDirectoryListing()

◆ getCurrentDirectory()

◆ changeDirectory()

◆ makeDirectory()

◆ removeDirectory()

◆ makeManyDirectories() [1/2]

◆ makeManyDirectories() [2/2]

◆ getDirectoryDetails()

◆ prepareSingleFile() [1/5]

◆ prepareSingleFile() [2/5]

◆ prepareSingleFile() [3/5]

◆ prepareSingleFile() [4/5]

◆ prepareSingleFile() [5/5]

◆ prepareRecursiveDir() [1/2]

◆ prepareRecursiveDir() [2/2]

◆ download() [1/2]

◆ upload() [1/2]

◆ download() [2/2]

◆ upload() [2/2]

◆ cancelTransfer()

◆ flush()

◆ getFileMD5() [1/4]

◆ getFileMD5() [2/4]

◆ getFileMD5() [3/4]

◆ getFileMD5() [4/4]

◆ getFileModificationTime()

◆ getFileSize() [1/2]

◆ getFileSize() [2/2]

◆ nameExists() [1/2]

◆ nameExists() [2/2]

◆ nameDoesNotExist() [1/2]

◆ nameDoesNotExist() [2/2]

◆ isFile() [1/2]

◆ isFile() [2/2]

◆ isDirectory() [1/2]

◆ isDirectory() [2/2]

◆ deleteFile() [1/2]

◆ deleteFile() [2/2]

◆ renameFile() [1/2]

◆ renameFile() [2/2]

◆ setStatsCallback()

◆ noop()

◆ raw()

◆ getMap()

◆ getOptimalUnitAndBlockSizes()

◆ detectApproximateUploadSpeed()

◆ detectApproximateDownloadSpeed()

◆ deleteTemporaryFiles()