fc::Options contains all the default and user-defined settings required by fc::Control to connect to FTP servers. More...
#include <FCOptions.hpp>
Public Member Functions | |
virtual | ~Options (void) |
Destructor. More... | |
Options (void) | |
Default constructor uses all built-in default values. More... | |
Options (const std::string &username, const std::string &password, const std::string &ip_or_hostname, const unsigned short int tcp_port=21) | |
Start with the same values as the default constructor, but provide an easy way to quickly specify the most-often used settings (username, password, FTP server). More... | |
virtual Options & | reset (void) |
Reset the Options object to use all of the built-in default values. More... | |
virtual fc::StrMap | getMap (const bool verbose=false) const |
Obtain a simple std::map representation of the options. More... | |
virtual std::string | getStr (const bool verbose=false) const |
Similar to fc::Options::getMap(), but formatted as a multi-line text string. More... | |
virtual Options & | setFtpServer (const std::string &ip_or_hostname, const unsigned short tcp_port=21) |
Set the FTP server address and port. More... | |
virtual Options & | setUsernameAndPassword (const std::string &username, const std::string &password) |
Set the username and password to use when connecting to the FTP server. More... | |
virtual Options & | setMode (const fc::ETransferMode tm=fc::kUdp, const fc::EConnectionMode cm=fc::kPassive) |
Set the FTP mode. More... | |
virtual Options & | setClientId (const fc::EClientIdMajor major_id=fc::kApi, const fc::EClientIdMinor minor_id=fc::kApiCpp) |
Set the client ID values needed by FileCatalyst servers. More... | |
virtual Options & | setTimeout (const int timeout=15) |
Set the socket timeout when reading and writing network sockets. More... | |
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. More... | |
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. More... | |
virtual Options & | setBandwidth (const fc::ECommonBandwidth full_bandwidth_bps, const fc::ECommonBandwidth slow_start_bandwidth_bps=fc::kZero_bps) |
Similar to fc::Options::setBandwidth( const uint64_t, const uint64_t ) but accepts fc::ECommonBandwidth enum as parameters. More... | |
virtual Options & | setCongestionControl (const bool enabled=false, const int aggression=2) |
Toggle the FileCatalyst UDP congestion control algorithm. More... | |
virtual Options & | setEncoders (const int number_of_encoders=3) |
Set the number of FileCatalyst server-based file encoders. More... | |
virtual Options & | setSocketOptions (const int socket_buffer_size_in_KiB=8192, const bool keepalive_enabled=true, const int keepalive_interval_in_seconds=55, const int keepalive_probes=9) |
Set socket-based options. More... | |
virtual Options & | setMd5Verification (const bool enabled=false, const int mode=0) |
Toggle MD5 verification. More... | |
virtual Options & | setEncryption (const bool enable_TCP_SSL=false, const bool enable_UDP_AES=true) |
Toggle control channel and data channel encryption. More... | |
virtual Options & | setSslHandshake (const fc::ESslHandshakeMode ssl_handshake_mode=fc::kSslAutoDetect) |
Set the SSL handshake handling. More... | |
virtual Options & | setLocaldir (const std::string &local_directory=".") |
Base path used when accessing local files. More... | |
virtual Options & | setRemotedir (const std::string &remote_directory="/") |
Base path used when accessing remote files. More... | |
virtual Options & | setTransferResume (const bool enabled=false, const int md5_chunk_size_in_KiB=16384) |
Toggle support for resuming incomplete partial file transfers. More... | |
virtual Options & | setOverwrite (const bool overwrite=false) |
Toggle whether destination files can be overwritten. More... | |
virtual Options & | setMultiThreaded (const bool multi_threaded=true, const int count=3) |
Toggle whether multiple threads are used for UDP transfers. More... | |
virtual Options & | setRetries (const int count=0, const int wait_period_in_seconds=30) |
Set the number of times that failed transfers should be retried and the length of the pause (in seconds) between each attempt. More... | |
virtual Options & | setTrace (const bool enabled=false) |
Toggle trace debug messages. More... | |
virtual Options & | setLogFileOutputDir (const std::string &dir="") |
Set the directory that FC++ uses for writing log files. More... | |
virtual Options & | setTmpFilenames (const bool enabled=false, const std::string &suffix=".part") |
Transfer files to a temporary name, then rename it once the transfer has completed. More... | |
virtual Options & | setSummaryLogging (const bool enabled=false) |
Write a summary log. More... | |
Static Public Member Functions | |
static fc::Local | getLogFileOutputDir (void) |
Static method to get the location where FileCatalyst C++ log files should be written. More... | |
fc::Options contains all the default and user-defined settings required by fc::Control to connect to FTP servers.
|
virtual |
Destructor.
fc::Options::Options | ( | void | ) |
Default constructor uses all built-in default values.
Use the various fc::Options::set...() methods to modify the options.
References reset().
fc::Options::Options | ( | const std::string & | username, |
const std::string & | password, | ||
const std::string & | ip_or_hostname, | ||
const unsigned short int | tcp_port = 21 |
||
) |
Start with the same values as the default constructor, but provide an easy way to quickly specify the most-often used settings (username, password, FTP server).
Note that port 21 is normally used for non-encrypted communication. The typical TCP port for secure (SSL) FTP is port 990.
References reset(), setFtpServer(), and setUsernameAndPassword().
|
virtual |
Reset the Options object to use all of the built-in default values.
This method is automatically called by the fc::Options constructor to ensure all fc::Options objects use the same default values.
References setBandwidth(), setClientId(), setCongestionControl(), setEncoders(), setEncryption(), setFtpServer(), setLimits(), setLocaldir(), setMd5Verification(), setMode(), setMultiThreaded(), setOverwrite(), setRemotedir(), setRetries(), setSocketOptions(), setSslHandshake(), setTimeout(), setTmpFilenames(), setTrace(), setTransferResume(), and setUsernameAndPassword().
|
virtual |
Obtain a simple std::map representation of the options.
This is mainly used for debug purposes, such as when fc::Exception objects are thrown.
[in] | verbose | determines if all fields should be included in the map. This can pose a security risk since verbose includes fields such as the username and password. |
References fc::Name::empty(), fc::formatBytesIEC(), fc::formatTimeDuration(), fc::formatTransferRate(), fc::Name::full(), getLogFileOutputDir(), fc::kFtp, fc::kSslAutoDetect, fc::kSslFullHandshake, fc::kSslSessionReuse, and fc::kUdp.
|
virtual |
Similar to fc::Options::getMap(), but formatted as a multi-line text string.
[in] | verbose | determines if all fields should be included in the map. This can pose a security risk since verbose includes fields such as the username and password. |
References getMap().
|
virtual |
Set the FTP server address and port.
If a hostname (instead of an IP address) is provided, it is immediately looked up via synchronous DNS lookup. It is up to the caller to ensure that DNS resolution is working prior to calling this method. By default, TCP/FTP is often on port 21. If encryption is enabled (see fc::Options::setEncryption) then the TCP/SSL port for secure FTP is often on port 990.
fc::Exception | if the server TCP port is invalid. |
fc::Exception | if the server's hostname cannot be resolved. |
References fc::SummaryLog::add(), FC_WHERE, and getMap().
|
virtual |
Set the username and password to use when connecting to the FTP server.
|
virtual |
Set the FTP mode.
[in] | tm | |
[in] | cm | Must be set to fc::kPassive. |
fc::Exception | if the transfer mode is not supported. |
fc::Exception | if the connection mode is not supported. |
References FC_WHERE, getMap(), fc::kFtp, fc::kPassive, and fc::kUdp.
|
virtual |
Set the client ID values needed by FileCatalyst servers.
This will be determined by your FileCatalyst license.
|
virtual |
Set the socket timeout when reading and writing network sockets.
[in] | timeout | Must be between 2 and 300 seconds. |
fc::Exception | if the socket timeout is out of range. |
References FC_WHERE, and getMap().
|
virtual |
Set the maximum unit and block size limits when using UDP mode transfers.
These values may need to be increased in some environments to achieve higher throughput.
[in] | unit_size_in_bytes | is the udp packet payload size. Must be between 64 B and 64 KiB. Normally is set to 1 KiB. |
[in] | block_size_in_bytes | is the size of udp "blocks" used to break up files when transferred via UDP. Must not be smaller than the unit size. Normally is set to 4 MiB. |
fc::Exception | if the unit size (udp packet payload) is out of range. |
fc::Exception | if the block size is smaller than a single udp packet size. |
References FC_WHERE, and getMap().
|
virtual |
Set the maximum and initial transfer rates which will be requested from the FileCatalyst server.
Bandwidth must be specified in bits-per-second.
[in] | full_bandwidth_bps | The maximum bandwidth rate to use during UDP or TCP file transfers. If the rate is set to zero, then FC++ will attempt to auto-detect a reasonable value. |
[in] | slow_start_bandwidth_bps | The initial starting transfer rate to use during UDP file transfers. If the rate is set to zero, then FC++ will attempt to auto-detect a reasonable value. This value is ignored when performing TCP/FTP transfers since TCP already has a slow-start mechanism. |
These bandwidth lines are equivalent ways of specifying the same value. Choose the style you prefer:
Bandwidth doesn't have to equate to one of the many enumerated values, nor to a specific common network speed. You can specify an exact value to use:
5 Mbps
means 5,000,000 bits/second
and not 5,242,880 bits/second.
The recommended approach in most scenarios is the following:
fc::Exception | if the bandwidth is out of range. |
References fc::bps(), FC_WHERE, getMap(), and fc::k10_Gbps.
|
virtual |
Similar to fc::Options::setBandwidth( const uint64_t, const uint64_t ) but accepts fc::ECommonBandwidth enum as parameters.
References fc::bps(), and setBandwidth().
|
virtual |
Toggle the FileCatalyst UDP congestion control algorithm.
This only applies to UDP-based transfers since TCP/FTP transfers use the normal TCP congestion control mechanisms. When enabled, FileCatalyst will automatically detect network conditions and dynamically adjust the rate at which a UDP transfer occurs.
For example, if you have a 100 Mbps link, and you want to transfer files as close as possible to 20 Mbps regardless of other network traffic, then you may choose to configure the transfer rate and leave congestion control off. This means the FileCatalyst client and server will transfer files as closely as they can to the requested speed of 20 Mbps, regardless of other traffic or network conditions, even if UDP packets are being dropped by an intermediate device.
If instead of setting the transfer rate to a fixed limit you want to transfer files as quickly as possible without interferring with other network traffic, then you likely want to enable the FileCatalyst UDP congestion control. This way, when your network link is relatively quiet, FileCatalyst will automatically increase the transfer rate. And when other traffic is on the network, FileCatalyst will temporarily slow down to prevent oversaturation of the network link.
[in] | enabled | Set to FALSE to have the FileCatalyst client and server attempt to transmit at the configured bandwidth regardless of network conditions. Set to TRUE to enable the FileCatalyst UDP congestion control. This only applies to UDP file transfers. |
[in] | aggression | The aggression value is ignored when the FileCatalyst UDP congestion control is disabled. When the FileCatalyst UDP congestion control is enabled, aggression controls how quickly the algorithm reacts to changing network conditions. For example, when set to 1 , the FileCatalyst client and server react cautiously, resulting in a lower retransmission rate, less network congestion, but possibly slower transfer. When set to 10 , the algorithm will attempt to recover as quickly as possible after a UDP packet drop has been detected. |
fc::Exception | if the aggression value is out of range. |
References FC_WHERE, and getMap().
|
virtual |
Set the number of FileCatalyst server-based file encoders.
When doing multi-threaded UDP transfers, a higher number of encoders on the server may result in higher performance, especially as the number of threads is increased.
[in] | number_of_encoders | Must be between 1 and 30. |
fc::Exception | if the number of encoders is out of range. |
References FC_WHERE, and getMap().
|
virtual |
Set socket-based options.
[in] | socket_buffer_size_in_KiB | is used to set both the receive and send socket buffer size for the data channel. Especially in the case of udp sockets, the default socket buffer size is extremely small resulting in poor performance. If necessary, multiple attempts are made by FC++ to change the receive and transmit socket buffer sizes for both TCP and UDP sockets. If the operating system does not accept the requested buffer size, FC++ automatically decreases the value and tries again. Must be between 1 and 32768 (1 KiB and 32 MiB). |
[in] | keepalive_enabled | determines whether keepalive probes are enabled on the TCP control channel. This is mapped to SO_KEEPALIVE in SOL_SOCKET. |
[in] | keepalive_interval_in_seconds | sets the time – in seconds – between TCP keepalive probes. This is mapped to TCP_KEEPIDLE and TCP_KEEPINTVL in SOL_TCP. On Windows, this maps to keepalivetime and keepaliveinterval of tcp_keepalive in SIO_KEEPALIVE_VALS. |
[in] | keepalive_probes | sets the maximum number of outstanding unanswered TCP keepalive probes. This is mapped to TCP_KEEPCNT in SOL_TCP. This parameter does nothing in Windows and OS X. |
/proc/sys/net/core/rmem_max
and /proc/sys/net/core/wmem_max
. For decent network performance when using FC++, these two values should be increased. See the socket(7)
man page for additional details on SO_RCVBUF
and SO_SNDBUF
.fc::Exception | if the socket buffer size is out of range. |
References FC_WHERE, and getMap().
|
virtual |
Toggle MD5 verification.
When MD5 verification is enabled, mode=0
is the only MD5 mode currently supported by the FileCatalyst C++ API. This will perform the MD5 verification after the entire file transfer has finished. When MD5 verification is disabled, mode
is ignored.
By default, MD5 verification is disabled.
[in] | enabled | Determines if the post-transfer md5 checksum is enabled. |
[in] | mode | Must be zero. |
fc::Exception | if the MD5 verification mode is non-zero. |
References FC_WHERE, and getMap().
|
virtual |
Toggle control channel and data channel encryption.
[in] | enable_TCP_SSL | controls 2 different settings:
|
[in] | enable_UDP_AES | applies to the UDP data channel, but is only used if the TCP control channel is also SSL encrypted. This means if you disable enable_TCP_SSL and enable enable_UDP_AES , the AES setting is ignored and the UDP data channel remain un-encrypted. |
|
virtual |
Set the SSL handshake handling.
When using TCP+SSL data connections, some servers expect the SSL connection to be setup a certain way. This can be used to force either the full ssl re-negotiation, or ssl session re-use.
[in] | ssl_handshake_mode | This must be set to fc::kSslFullHandshake or fc::kSslAutoDetect when connecting to File Catalyst servers. |
|
virtual |
Base path used when accessing local files.
This path will be used only when files are specified using relative filenames.
|
virtual |
Base path used when accessing remote files.
This path will be used only when files are specified using relative filenames.
|
virtual |
Toggle support for resuming incomplete partial file transfers.
[in] | enabled | Determines if support for resuming transfers is supported. |
[in] | md5_chunk_size_in_KiB | If resuming transfers is enabled, a partial MD5 checksum of the file will be performed. This parameter can be used to modify how much of the file is checksumed. |
For example, on a 7 GiB file where only 5 GiB was previously transferred, enabling transfer resume with the default value will cause a MD5 checksum of the last 1024 KiB (1 MiB) of the partial file, and only if the MD5 checksums match will the transfer be resumed from the point where it was interrupted.
If the MD5 checksum doesn't match, the entire file is re-sent.
Ideally, the chunk size to be verified should be larger than the total number of blocks in transit in case a block was only partially written when the file transfer was interrupted.
fc::Exception | if the MD5 chunk size is out of range. |
References FC_WHERE, and getMap().
|
virtual |
Toggle whether destination files can be overwritten.
|
virtual |
Toggle whether multiple threads are used for UDP transfers.
[in] | multi_threaded | is only used with udp-mode transfers. |
[in] | count | is only used when multi_threaded has been set to true . Must be between 1 and 40. |
fc::Exception | if the thread count is out of range. |
References FC_WHERE, and getMap().
|
virtual |
Set the number of times that failed transfers should be retried and the length of the pause (in seconds) between each attempt.
If a transfer retry is necessary, both auto-resume and overwrite will also be automatically enabled.
[in] | count | Must be between 1 and 99. |
[in] | wait_period_in_seconds | Must be between 1 and 86400 (24 hours). |
fc::Exception | if the retry count is out of range. |
fc::Exception | if the retry pause length is out of range. |
References FC_WHERE, and getMap().
|
virtual |
Toggle trace debug messages.
This is only supported for UDP upload.
When enabled, a file named "fc_trace.log"
will be created in the current working directory and FC++ trace messages will be appended to it during UDP uploads. These messages can be reviewed to help determine bottlenecks or problems.
fccl
by specifying the undocumented command –trace
. References output_log_directory.
|
virtual |
Set the directory that FC++ uses for writing log files.
By default, log files are disabled. But when enabled (for example by calling fc::Options::setTrace() or fc::Exception::createLogFile()) then the log files will be written to the current working directory, or to the local directory specified in setLogFileOutputDir().
References fc::Name::full(), and fc::Name::name().
|
static |
Static method to get the location where FileCatalyst C++ log files should be written.
If multiple locations have been specified in different fc::Options objects, this will only return the very last one set by setLogFileOutputDir().
References output_log_directory.
|
virtual |
Transfer files to a temporary name, then rename it once the transfer has completed.
|
virtual |
Write a summary log.