FC++  v0.9.0-9e9b65
FileCatalyst Fast File Transfers - C++ Library
fc::Control Class Referencefinal

More...

#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...
 
Controloperator= (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::GlobalStateAndStatsgetGlobalStateAndStats () const
 Get a reference to the global FC++ state and file transfer statistics for the control object. More...
 
fc::ControlclearGlobalStats ()
 Clear all of the file transfer statistics. More...
 
fc::ControlclearFileMap ()
 Clear the map of pending file transfers. More...
 
const fc::TransferStatsMapgetFileMap () 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::TransferStatsgetMostRecentFileStats () const
 Gets the most recent file transfer statistics. More...
 
Controlconnect ()
 Connect the fc::Control object to the specified FTP server. More...
 
Controldisconnect ()
 Disconnect the fc::Control object from the FTP server. More...
 
const fc::OptionsgetOptions () const
 Get the current set of options. More...
 
ControlsetNewOptions (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...
 
ControlprepareSingleFile (const fc::Remote &remote)
 Queue a single file for transfer. More...
 
ControlprepareSingleFile (const fc::Local &local)
 Queue a single file for transfer. More...
 
ControlprepareSingleFile (const fc::Remote &remote, const fc::Local &local)
 Queue a single file for transfer. More...
 
ControlprepareSingleFile (const fc::Local &local, const fc::Remote &remote)
 Queue a single file for transfer. More...
 
ControlprepareSingleFile (const char *const content, const size_t len, const fc::Remote &remote)
 Queue a single file for upload. More...
 
ControlprepareRecursiveDir (const fc::Remote &remote, const fc::Local &local)
 Queue many files/directories for transfer. More...
 
ControlprepareRecursiveDir (const fc::Local &local, const fc::Remote &remote)
 Queue many files/directories for transfer. More...
 
Controldownload ()
 Immediately download all files that have been queued for transfer. More...
 
Controlupload ()
 Immediately upload all files that have been queued for transfer. More...
 
Controldownload (const fc::Remote &remote)
 Download a single file from the FTP server. More...
 
Controlupload (const fc::Local &local)
 Upload a single file to the FTP server. More...
 
ControlcancelTransfer ()
 Cancel the current file transfer (and all remaining files if multiple files have been prepared). More...
 
Controlflush ()
 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...
 
ControldeleteFile (const fc::Remote &remoteFile)
 Delete a remote file. More...
 
ControldeleteFile (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...
 
ControlrenameFile (const fc::Local &localFrom, const fc::Local &localTo)
 Rename a local file. More...
 
ControlsetStatsCallback (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...
 
Controlnoop ()
 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...
 
ControlgetOptimalUnitAndBlockSizes (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...
 
ControldeleteTemporaryFiles ()
 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.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/aThis 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/aThis 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/aThis 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();
{
... // 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/aThis 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::Exceptionif 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::Exceptionif 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.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::Exceptionif 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" ) );
See also
fc::GlobalStats
Exceptions
fc::Exceptionif 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.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
// we can then proceed to queue up new files or directories again
Exceptions
fc::Exceptionif 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.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::Exceptionif 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::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif a connection to the server has already been established.
fc::Exceptionif boost::asio returned an error establishing the SSL control channel connection to the server.
fc::Exceptionif boost::asio returned an error performing the SSL handshake on the control channel connection.
fc::Exceptionif boost::asio returned an error establishing a non-encrypted TCP control channel connection to the server.
fc::Exceptionif the server didn't send anything to read on the non-encrypted TCP control channel.
fc::Exceptionif the server response is unexpected.
fc::Exceptionif 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::Exceptionif 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::Exceptionif 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::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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 );
v.push_back( "/projectA/testing/output" );
v.push_back( "/projectA/bin/debug" );

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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the remote filename is empty.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the local filename is empty.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the remote directory name is empty.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the local directory name is empty.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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.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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the remote filename is empty.
fc::Exceptionif 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.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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the local filename is empty.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the offset is invalid.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif 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::Exceptionif 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::Exceptionif 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::Exceptionif 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::Exceptionif 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::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif boost::asio returned an error while sending the command to the server.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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::Exceptionif 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_bytesSize of the file to be sent or received via UDP.
[in,out]unit_size_in_bytesOn 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_bytesOn 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif 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_refreshUpload 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the server is not licensed for UDP.
fc::Exceptionif the server is a traditional (non-FileCatalyst) FTP server.
fc::Exceptionif 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::Exceptionif this method is called on a C++ object that has been moved and is no longer valid internally.
fc::Exceptionif the server is not licensed for UDP.
fc::Exceptionif the server is a traditional (non-FileCatalyst) FTP server.
fc::Exceptionif 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:
fc::Control::makeDirectory
std::string makeDirectory(const fc::Remote &directory)
Create a new directory on the FTP server.
Definition: FCControl.cpp:334
fc::Control::prepareSingleFile
Control & prepareSingleFile(const fc::Remote &remote)
Queue a single file for transfer.
Definition: FCControl.cpp:399
fc::Control::getDirectoryListing
std::string getDirectoryListing(const fc::Remote &directory=fc::Remote(""))
Get a directory listing from the FTP server.
Definition: FCControl.cpp:295
fc::Options::setMode
virtual Options & setMode(const fc::ETransferMode tm=fc::kUdp, const fc::EConnectionMode cm=fc::kPassive)
Set the FTP mode.
Definition: FCOptions.cpp:356
fc::Control::upload
Control & upload()
Immediately upload all files that have been queued for transfer.
Definition: FCControl.cpp:607
fc::GlobalStateAndStats::stats
GlobalStats stats
Global statistics.
Definition: FCStateAndStats.hpp:133
fc::Options::setFtpServer
virtual Options & setFtpServer(const std::string &ip_or_hostname, const unsigned short tcp_port=21)
Set the FTP server address and port.
Definition: FCOptions.cpp:303
fc::Control::getFileSize
uint64_t getFileSize(const fc::Local &local)
Get the size of the specified remote file.
Definition: FCControl.cpp:789
fc::formatBytesSI
std::string formatBytesSI(const uint64_t bytes)
Format the payload bytes using SI units (1000 bytes per "K").
Definition: FCTransferStats.cpp:639
fc::Options::setUsernameAndPassword
virtual Options & setUsernameAndPassword(const std::string &username, const std::string &password)
Set the username and password to use when connecting to the FTP server.
Definition: FCOptions.cpp:347
fc::TransferStats
File transfer statistics.
Definition: FCTransferStats.hpp:37
fc::Control::makeManyDirectories
int makeManyDirectories(const fc::StrVec &directories)
Create multiple directories on the FTP server.
Definition: FCControl.cpp:360
fc::Control::getFileMap
const fc::TransferStatsMap & getFileMap() const
Get a reference to the transfer file map.
Definition: FCControl.cpp:167
fc::Control::changeDirectory
std::string changeDirectory(const fc::Remote &directory)
Change the working directory on the FTP server.
Definition: FCControl.cpp:321
fc
Definition: FCControl.hpp:17
fc::Control::isFile
bool isFile(const fc::Local &local)
Determine if the specified name is a filename.
Definition: FCControl.cpp:839
fc::Mbps
uint64_t Mbps(const int rate)
Convert easy-to-use numerical values to bps values.
Definition: FCOptions.hpp:271
fc::Control::getFileMD5
std::string getFileMD5(const fc::Local &local)
Get the MD5 signature of the specified local file.
Definition: FCControl.cpp:724
fc::formatBytesIEC
std::string formatBytesIEC(const uint64_t bytes)
Format the payload bytes using IEC units (1024 bytes per "K").
Definition: FCTransferStats.cpp:646
fc::FileDetails
A collection of file or directory properties returned when a directory listing has been requested.
Definition: FCUtils.hpp:145
fc::Control::getOptimalUnitAndBlockSizes
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.
Definition: FCControl.cpp:971
fc::Options::setLimits
virtual Options & setLimits(const int unit_size_in_bytes=1024, const int block_size_in_bytes=4194304)
Set the maximum unit and block size limits when using UDP mode transfers.
Definition: FCOptions.cpp:402
fc::StrVec
std::vector< std::string > StrVec
Defined for convenience: a vector of text strings.
Definition: FCUtils.hpp:25
fc::Control::cancelTransfer
Control & cancelTransfer()
Cancel the current file transfer (and all remaining files if multiple files have been prepared).
Definition: FCControl.cpp:694
fc::Options
fc::Options contains all the default and user-defined settings required by fc::Control to connect to ...
Definition: FCOptions.hpp:282
fc::Control::flush
Control & flush()
Flush the TCP control channel.
Definition: FCControl.cpp:709
fc::Control::removeDirectory
std::string removeDirectory(const fc::Remote &directory)
Remove an empty directory on the FTP server.
Definition: FCControl.cpp:347
fc::Remote
The class fc::Remote is used to encapsulate remote directories or files.
Definition: FCPath.hpp:160
fc::Control::isDirectory
bool isDirectory(const fc::Local &local)
Determine if the specified name is a directory.
Definition: FCControl.cpp:863
fc::GlobalStateAndStats
Combine both state and statistics into a single class which callers can access.
Definition: FCStateAndStats.hpp:114
fc::Control::renameFile
std::string renameFile(const fc::Remote &remoteFrom, const fc::Remote &remoteTo)
Rename a remote file.
Definition: FCControl.cpp:915
fc::Control::isConnected
bool isConnected() const
Quickly determine if the fc::Control object is connected to a FTP server.
Definition: FCControl.cpp:75
fc::Control::getGlobalStateAndStats
const fc::GlobalStateAndStats & getGlobalStateAndStats() const
Get a reference to the global FC++ state and file transfer statistics for the control object.
Definition: FCControl.cpp:127
fc::TransferStatsMap
std::map< size_t, fc::TransferStats > TransferStatsMap
Track all of the individual file transfers, where the key is a numeric sequence describing the order ...
Definition: FCStateAndStats.hpp:24
fc::Control::getFileModificationTime
std::string getFileModificationTime(const fc::Remote &remote)
Get the modification timestamp of the specified remote file.
Definition: FCControl.cpp:776
fc::formatTransferRate
std::string formatTransferRate(const uint64_t bps)
Format the transfer rate statistic using the common descriptions Kbps, Mbps, etc.
Definition: FCTransferStats.cpp:621
fc::Control::clearFileMap
fc::Control & clearFileMap()
Clear the map of pending file transfers.
Definition: FCControl.cpp:153
fc::Control::detectApproximateDownloadSpeed
uint64_t detectApproximateDownloadSpeed(const bool force_refresh=false)
Get an approximation of the available download transfer rate between the FC++ client and server.
Definition: FCControl.cpp:1070
fc::Control::nameExists
bool nameExists(const fc::Local &local)
Determine if a file or directory exists with the given name.
Definition: FCControl.cpp:815
fc::Control::connect
Control & connect()
Connect the fc::Control object to the specified FTP server.
Definition: FCControl.cpp:204
fc::Control::download
Control & download()
Immediately download all files that have been queued for transfer.
Definition: FCControl.cpp:560
fc::Control::getCurrentDirectory
std::string getCurrentDirectory()
Get the current directory from the FTP server.
Definition: FCControl.cpp:308
fc::FDVec
std::vector< FileDetails > FDVec
A std::vector of fc::FileDetails.
Definition: FCUtils.hpp:158
fc::Control::getDirectoryDetails
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.
Definition: FCControl.cpp:386
fc::Control::isLoggedIn
bool isLoggedIn() const
Quickly determine if the fc::Control object has completed the login process.
Definition: FCControl.cpp:83
fc::Control::isFileCatalystServer
bool isFileCatalystServer() const
Quickly determine if the FTP server supports the FileCatalyst extensions.
Definition: FCControl.cpp:93
fc::Options::setMd5Verification
virtual Options & setMd5Verification(const bool enabled=false, const int mode=0)
Toggle MD5 verification.
Definition: FCOptions.cpp:525
fc::Control::getOptions
const fc::Options & getOptions() const
Get the current set of options.
Definition: FCControl.cpp:269
fc::Control::setNewOptions
Control & setNewOptions(const fc::Options &newOptions)
Set new options.
Definition: FCControl.cpp:281
fc::Options::setBandwidth
virtual Options & setBandwidth(const uint64_t full_bandwidth_bps=fc::bps(fc::kZero_bps), const uint64_t slow_start_bandwidth_bps=fc::bps(fc::kZero_bps))
Set the maximum and initial transfer rates which will be requested from the FileCatalyst server.
Definition: FCOptions.cpp:440
fc::Control::clearGlobalStats
fc::Control & clearGlobalStats()
Clear all of the file transfer statistics.
Definition: FCControl.cpp:139
fc::Local
The class fc::Local is used to encapsulate local directories or files.
Definition: FCPath.hpp:141
fc::kUdp
@ kUdp
2 UDP (FileCatalyst mode)
Definition: FCOptions.hpp:51
fc::Control::nameDoesNotExist
bool nameDoesNotExist(const fc::Local &local)
Determine if a file or directory already exists with this name.
Definition: FCControl.hpp:1096
fc::Control
Definition: FCControl.hpp:52
fc::Control::deleteFile
Control & deleteFile(const fc::Remote &remoteFile)
Delete a remote file.
Definition: FCControl.cpp:887
fc::GlobalStateAndStats::fileStatsMap
TransferStatsMap fileStatsMap
Track statistics on all individual file transfers.
Definition: FCStateAndStats.hpp:136
fc::Control::prepareRecursiveDir
Control & prepareRecursiveDir(const fc::Remote &remote, const fc::Local &local)
Queue many files/directories for transfer.
Definition: FCControl.cpp:498