fc::Control is the client class C++ API used to control a FTP server and manage file transfers. 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... | |
Control & | operator= (Control &&rhs) |
C++11 move assignment. More... | |
~Control (void) | |
Destructing the fc::Control object terminates any connection to the ftp server. More... | |
bool | isValid (void) 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 (void) const |
Quickly determine if the fc::Control object is connected to a FTP server. More... | |
bool | isLoggedIn (void) const |
Quickly determine if the fc::Control object has completed the login process. More... | |
bool | isFileCatalystServer (void) const |
Quickly determine if the FTP server supports the FileCatalyst extensions. More... | |
std::string | getCurrentServerReplyString (void) const |
Quickly retrieve the last result string received from the FTP server. More... | |
fc::FtpServerReplyCodes | getCurrentServerReplyCode (void) const |
Quickly retrieve the most recent result code received from the FTP server. More... | |
const fc::GlobalStateAndStats & | getGlobalStateAndStats (void) const |
Get a reference to the global FC++ state and file transfer statistics for the control object. More... | |
fc::Control & | clearGlobalStats (void) |
Clear all of the file transfer statistics. More... | |
fc::Control & | clearFileMap (void) |
Clear the map of pending file transfers. More... | |
const fc::TransferStatsMap & | getFileMap (void) const |
Get a reference to the transfer file map. More... | |
size_t | getFileMapIndex (void) const |
Get the current index into the transfer file map. More... | |
const fc::TransferStats & | getMostRecentFileStats (void) const |
Gets the most recent file transfer statistics. More... | |
Control & | connect (void) |
Connect the fc::Control object to the specified FTP server. More... | |
Control & | disconnect (void) |
Disconnect the fc::Control object from the FTP server. More... | |
const fc::Options & | getOptions (void) 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 (void) |
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=true) |
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 & | 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 (void) |
Immediately download all files that have been queued for transfer. More... | |
Control & | upload (void) |
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 (void) |
Cancel the current file transfer (and all remaining files if multiple files have been prepared). More... | |
Control & | flush (void) |
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::Remote &remote) |
Determine if a file or directory exists with the given name. More... | |
bool | nameDoesNotExist (const fc::Remote &remote) |
Determine if a file or directory already exists with this name. More... | |
bool | isFile (const fc::Remote &remote) |
Determine if the specified name is a filename. 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 & | 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 (void) |
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 (void) 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... | |
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.
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:
For example:
Then in the rest of your code, you'd obtain a reference to that "global" FTP object:
References Control().
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().
fc::Control::~Control | ( | void | ) |
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().
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.
bool fc::Control::isValid | ( | void | ) | 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.
n/a | This will return immmediately. It does not throw. |
bool fc::Control::isConnected | ( | void | ) | const |
Quickly determine if the fc::Control object is connected to a FTP server.
n/a | This will return immmediately. It does not throw. |
bool fc::Control::isLoggedIn | ( | void | ) | 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.
true
.n/a | This will return immmediately. It does not throw. |
bool fc::Control::isFileCatalystServer | ( | void | ) | 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.
true
.n/a | This will return immmediately. It does not throw. |
std::string fc::Control::getCurrentServerReplyString | ( | void | ) | 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 |
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
fc::FtpServerReplyCodes fc::Control::getCurrentServerReplyCode | ( | void | ) | 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 |
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
const fc::GlobalStateAndStats & fc::Control::getGlobalStateAndStats | ( | void | ) | const |
Get a reference to the global FC++ state and file transfer statistics for the control object.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
fc::Control & fc::Control::clearGlobalStats | ( | void | ) |
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::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
fc::Control & fc::Control::clearFileMap | ( | void | ) |
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.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
const fc::TransferStatsMap & fc::Control::getFileMap | ( | void | ) | const |
Get a reference to the transfer file map.
This is the same as calling getGlobalStateAndStats() and dereferencing fileStatsMap
.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
size_t fc::Control::getFileMapIndex | ( | void | ) | const |
Get the current index into the transfer file map.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
const fc::TransferStats & fc::Control::getMostRecentFileStats | ( | void | ) | 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.
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.
fc::Control & fc::Control::connect | ( | void | ) |
Connect the fc::Control object to the specified FTP server.
Will return once the connect and login process have finished.
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.
fc::Control & fc::Control::disconnect | ( | void | ) |
Disconnect the fc::Control object from the FTP server.
This is automatically called when a fc::Control object goes out of scope.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
const fc::Options & fc::Control::getOptions | ( | void | ) | const |
Get the current set of options.
This can be used to modify the existing set of options.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
fc::Control & fc::Control::setNewOptions | ( | const fc::Options & | newOptions | ) |
Set new options.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
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::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.
std::string fc::Control::getCurrentDirectory | ( | void | ) |
Get the current directory from the FTP server.
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.
std::string fc::Control::changeDirectory | ( | const fc::Remote & | directory | ) |
Change the working directory on the FTP server.
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.
std::string fc::Control::makeDirectory | ( | const fc::Remote & | directory | ) |
Create a new directory on the FTP server.
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.
std::string fc::Control::removeDirectory | ( | const fc::Remote & | directory | ) |
Remove an empty directory on the FTP server.
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.
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:
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
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.
int fc::Control::makeManyDirectories | ( | const fc::Remote & | directory | ) |
Create a directory for each element in the specified path.
For example:
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
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.
fc::FDVec fc::Control::getDirectoryDetails | ( | const fc::Remote & | directory = fc::Remote(".") , |
const bool | getMd5 = true |
||
) |
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.
The MD5 checksum can be expensive to run on very large files or on directories with thousands of files. Set getMd5
to false
to disable retrieving the md5 checksum of each file.
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.
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::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.
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::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.
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.
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:
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.
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.
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:
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.
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::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.
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::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, fc::formatTimeDuration(), fc::GlobalStateAndStats::kPauseForRetry, fc::Options::setOverwrite(), and fc::Options::setTransferResume().
fc::Control & fc::Control::download | ( | void | ) |
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().
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.
fc::Control & fc::Control::upload | ( | void | ) |
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().
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.
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.
This is equivalent to:
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 download(), and FC_WHERE.
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.
This is equivalent to:
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, and upload().
fc::Control & fc::Control::cancelTransfer | ( | void | ) |
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().
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.
fc::Control & fc::Control::flush | ( | void | ) |
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:
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.
std::string fc::Control::getFileMD5 | ( | const fc::Local & | local | ) |
Get the MD5 signature of the specified local file.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
std::string fc::Control::getFileMD5 | ( | const fc::Remote & | remote | ) |
Get the MD5 signature of the specified remote file.
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.
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.
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.
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.
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.
std::string fc::Control::getFileModificationTime | ( | const fc::Remote & | remote | ) |
Get the modification timestamp of the specified remote file.
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.
uint64_t fc::Control::getFileSize | ( | const fc::Local & | local | ) |
Get the size of the specified remote file.
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.
uint64_t fc::Control::getFileSize | ( | const fc::Remote & | remote | ) |
Get the size of the specified remote file.
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.
bool fc::Control::nameExists | ( | const fc::Remote & | remote | ) |
Determine if a file or directory exists with the given name.
TRUE
if a file or directory already exists with this name.fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
|
inline |
Determine if a file or directory already exists with this name.
TRUE
if nothing exists with the given name.References deleteFile(), detectApproximateDownloadSpeed(), detectApproximateUploadSpeed(), getMap(), getOptimalUnitAndBlockSizes(), isDirectory(), isFile(), fc::kOkay, nameExists(), noop(), operator=(), raw(), renameFile(), and setStatsCallback().
bool fc::Control::isFile | ( | const fc::Remote & | remote | ) |
Determine if the specified name is a filename.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
bool fc::Control::isDirectory | ( | const fc::Remote & | remote | ) |
Determine if the specified name is a directory name.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
fc::Control & fc::Control::deleteFile | ( | const fc::Remote & | remoteFile | ) |
Delete a remote file.
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.
fc::Control & fc::Control::deleteFile | ( | const fc::Local & | localFile | ) |
Delete a local file.
fc::Exception | if the file cannot be deleted. |
References FC_WHERE, and fc::Name::full().
std::string fc::Control::renameFile | ( | const fc::Remote & | remoteFrom, |
const fc::Remote & | remoteTo | ||
) |
Rename a remote file.
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.
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.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
fc::Control & fc::Control::noop | ( | void | ) |
Send a NO-OP to the server.
Can be useful to confirm the control object is still connected to the FTP server.
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.
std::string fc::Control::raw | ( | const std::string & | cmd, |
const fc::FtpServerReplyCodes | expectedReply = fc::kOkay |
||
) |
Send an unmanaged raw command to the server.
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, and getCurrentServerReplyString().
fc::StrMap fc::Control::getMap | ( | void | ) | const |
Get a map of all current settings and values. Used mostly for debug purpose.
fc::Exception | if this method is called on a C++ object that has been moved and is no longer valid internally. |
References FC_WHERE.
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.
[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. |
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. 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:
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::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, getOptions(), and stats.
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.
[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:
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::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 a traditional (non-FileCatalyst) FTP server. |
fc::Exception | if the server response is unexpected. |
References FC_WHERE.
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.
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 a traditional (non-FileCatalyst) FTP server. |
fc::Exception | if the server response is unexpected. |
References FC_WHERE.