FC++  v0.7.2-1128
FileCatalyst Fast File Transfers - C++ Library
fc::Options Class Reference

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 Optionsreset (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 OptionssetFtpServer (const std::string &ip_or_hostname, const unsigned short tcp_port=21)
 Set the FTP server address and port. More...
 
virtual OptionssetUsernameAndPassword (const std::string &username, const std::string &password)
 Set the username and password to use when connecting to the FTP server. More...
 
virtual OptionssetMode (const fc::ETransferMode tm=fc::kUdp, const fc::EConnectionMode cm=fc::kPassive)
 Set the FTP mode. More...
 
virtual OptionssetClientId (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 OptionssetTimeout (const int timeout=15)
 Set the socket timeout when reading and writing network sockets. More...
 
virtual OptionssetLimits (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 OptionssetBandwidth (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 OptionssetBandwidth (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 OptionssetCongestionControl (const bool enabled=false, const int aggression=2)
 Toggle the FileCatalyst UDP congestion control algorithm. More...
 
virtual OptionssetEncoders (const int number_of_encoders=5)
 Set the number of FileCatalyst server-based file encoders. More...
 
virtual OptionssetSocketOptions (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 OptionssetMd5Verification (const bool enabled=false, const int mode=0)
 Toggle MD5 verification. More...
 
virtual OptionssetEncryption (const bool enable_TCP_SSL=false, const bool enable_UDP_AES=true)
 Toggle control channel and data channel encryption. More...
 
virtual OptionssetSslHandshake (const fc::ESslHandshakeMode ssl_handshake_mode=fc::kSslAutoDetect)
 Set the SSL handshake handling. More...
 
virtual OptionssetLocaldir (const std::string &local_directory=".")
 Base path used when accessing local files. More...
 
virtual OptionssetRemotedir (const std::string &remote_directory="/")
 Base path used when accessing remote files. More...
 
virtual OptionssetTransferResume (const bool enabled=false, const int md5_chunk_size_in_KiB=16384)
 Toggle support for resuming incomplete partial file transfers. More...
 
virtual OptionssetOverwrite (const bool overwrite=false)
 Toggle whether destination files can be overwritten. More...
 
virtual OptionssetMultiThreaded (const bool multi_threaded=true, const int count=3)
 Toggle whether multiple threads are used for UDP transfers. More...
 
virtual OptionssetRetries (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 OptionssetTrace (const bool enabled=false)
 Toggle trace debug messages. More...
 
virtual OptionssetLogFileOutputDir (const std::string &dir="")
 Set the directory that FC++ uses for writing log files. More...
 
virtual OptionssetTmpFilenames (const bool enabled=false, const std::string &suffix=".tmp", const std::string &prefix="")
 When uploading or downloading files, sometimes the target filename should not be overwritten or made available until the transfer has finished successfully. More...
 
virtual OptionssetSummaryLogging (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...
 

Detailed Description

fc::Options contains all the default and user-defined settings required by fc::Control to connect to FTP servers.

Constructor & Destructor Documentation

◆ ~Options()

fc::Options::~Options ( void  )
virtual

Destructor.

◆ Options() [1/2]

fc::Options::Options ( void  )

Default constructor uses all built-in default values.

Use the various fc::Options::set...() methods to modify the options.

See also
fc::Control where the constructor is provided with a fc::Options object.

References reset().

Here is the call graph for this function:

◆ Options() [2/2]

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.

See also
fc::Control where the constructor is provided with a fc::Options object.
CLI Example Description
fccl –user bob ... Username.
fccl –passwd secret ... Password.
fccl –host 1.2.3.4 ... Hostname or IP address.
fccl –port 21 ... TCP port for the control channel.

References reset(), setFtpServer(), and setUsernameAndPassword().

Here is the call graph for this function:

Member Function Documentation

◆ reset()

fc::Options & fc::Options::reset ( void  )
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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getMap()

fc::StrMap fc::Options::getMap ( const bool  verbose = false) const
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.

Parameters
[in]verbosedetermines 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.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getStr()

std::string fc::Options::getStr ( const bool  verbose = false) const
virtual

Similar to fc::Options::getMap(), but formatted as a multi-line text string.

Parameters
[in]verbosedetermines 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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setFtpServer()

fc::Options & fc::Options::setFtpServer ( const std::string &  ip_or_hostname,
const unsigned short  tcp_port = 21 
)
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.

CLI Example Description
fccl –host 1.2.3.4 ... Hostname or IP address.
fccl –port 21 ... TCP port for the control channel.
Exceptions
fc::Exceptionif the server TCP port is invalid.
fc::Exceptionif the server's hostname cannot be resolved.

References fc::SummaryLog::add(), FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setUsernameAndPassword()

fc::Options & fc::Options::setUsernameAndPassword ( const std::string &  username,
const std::string &  password 
)
virtual

Set the username and password to use when connecting to the FTP server.

CLI Example Description
fccl –user bob ... Username.
fccl –passwd secret ... Password.
Here is the caller graph for this function:

◆ setMode()

fc::Options & fc::Options::setMode ( const fc::ETransferMode  tm = fc::kUdp,
const fc::EConnectionMode  cm = fc::kPassive 
)
virtual

Set the FTP mode.

Parameters
[in]tm
  • Set to fc::kUdp to use the accelerated FileCatalyst transfer mode.
  • Set to fc::kFtp to use legacy TCP/FTP compatible mode.
[in]cmMust be set to fc::kPassive.
CLI Example Description
fccl –mode tcp ... Use traditional TCP/FTP transfer method.
fccl –mode ftp ... Alias for "tcp".
fccl –mode udp ... Use Unlimi-Tech's FileCatalyst UDP transfer method.
Exceptions
fc::Exceptionif the transfer mode is not supported.
fc::Exceptionif the connection mode is not supported.

References FC_WHERE, getMap(), fc::kFtp, fc::kPassive, and fc::kUdp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setClientId()

fc::Options & fc::Options::setClientId ( const fc::EClientIdMajor  major_id = fc::kApi,
const fc::EClientIdMinor  minor_id = fc::kApiCpp 
)
virtual

Set the client ID values needed by FileCatalyst servers.

This will be determined by your FileCatalyst license.

Here is the caller graph for this function:

◆ setTimeout()

fc::Options & fc::Options::setTimeout ( const int  timeout = 15)
virtual

Set the socket timeout when reading and writing network sockets.

See also
fc::Options::setSocketOptions()
CLI Example Description
fccl –timeout 30 ... Socket timeout in seconds.
Parameters
[in]timeoutMust be between 2 and 300 seconds.
Exceptions
fc::Exceptionif the socket timeout is out of range.

References FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setLimits()

fc::Options & fc::Options::setLimits ( const int  unit_size_in_bytes = 1024,
const int  block_size_in_bytes = 4194304 
)
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.

Warning
If the network experiences UDP packet drops, a unit size greater than the MTU will result in extremely poor UDP transfer performance due to the increased number of retransmissions required for each unit in a block.
Note
When used on a network with jumbo packet support, remember to increase the unit size to take advantage of the larger packets.
CLI Example Description
fccl –unitsize 1400 ... Unit size (packet size).
fccl –blocksize 2097152 ... Block size.
See also
--blocksize and --unitsize
Parameters
[in]unit_size_in_bytesis the udp packet payload size. Must be between 64 B and 64 KiB. Normally is set to 1 KiB.
[in]block_size_in_bytesis 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.
Note
The unit and block sizes are the maximum allowed, and may be automatically reduced. FC++ will optimize these values when necessary to best transfer a file based on the individual file sizes.
For example, given these default values:
  • unit size of 1 KiB
  • block size of 4 MiB
When sending a 5.00 MiB file, the block size will automatically be reduced from 4 MiB to 2.5 MiB to ensure the entire file can be sent in 2 full blocks without any internal FC++ padding.
Warning
The unit and block sizes are only auto-optimized for files less than 1 GiB in size. For larger files, the exact unit and block size specified will be used. This normally isn't an issue since any internal padding required by FC++ will represent a nearly insignificant percentage of the total number of bytes transfered.
Exceptions
fc::Exceptionif the unit size (udp packet payload) is out of range.
fc::Exceptionif the block size is smaller than a single udp packet size.

References FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setBandwidth() [1/2]

fc::Options & fc::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) 
)
virtual

Set the maximum and initial transfer rates which will be requested from the FileCatalyst server.

Bandwidth must be specified in bits-per-second.

Parameters
[in]full_bandwidth_bpsThe 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_bpsThe 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.
Note
Using auto-detection (setting the maximum bandwidth rate or the slow start rate to zero) requires the use of a FileCatalyst server, and detection is performed using UDP traffic. Auto-detection wont work when connecting to traditional TCP/FTP servers, or in network environments where UDP traffic is blocked.

These bandwidth lines are equivalent ways of specifying the same value. Choose the style you prefer:

fc::Options options;
options.setBandwidth( fc::k100_Mbps ); // uses one of the many enumerations
options.setBandwidth( fc::bps(fc::kFastEthernet) ); // uses one of the many enumerations (explicit conversion to bps)
options.setBandwidth( fc::Gbps(0.1) ); // uses the function which defines 1 Gbps
options.setBandwidth( fc::Mbps(100) ); // uses the function which defines 1 Mbps
options.setBandwidth( fc::Kbps(100) * 1000 ); // uses 100 Kbps * 1000
options.setBandwidth( 100000000 ); // uses raw bps value

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:

fc::Options options;
options.setBandwidth( 56789 ); // just slightly more than fc::k56_Kbps
Note
Remember that network link speeds use the SI (metric) naming method. For example, 5 Mbps means 5,000,000 bits/second and not 5,242,880 bits/second.

The recommended approach in most scenarios is the following:

  • Turn on congestion control using fc::Options::setCongestionControl().
  • Set the maximum to a value equal to or larger than your expected network bandwidth.
  • Optionally, set the initial start rate to a value equal to or less than the maximum.
Warning
In situations where UDP congestion control is disabled, setting the desired maximum and start bandwidth rate is extremely important. Without UDP congestion control, transfer rates that are set too high will cause FC++ to flood the network, resulting in poor file transfers and degraded network performance. It is strongly recommended that UDP congestion control be enabled when using fc::kUdp mode.
CLI Example Description
fccl –bandwidth 1500 ... Maximum bandwidth. The CLI uses Kbps. For example, "1500" in the CLI means 1500 * 1000 = 1,500,000 bps or 1.5 Mbps.
fccl –startrate 600 ... Initial slow start rate. The CLI uses Kbps. For example, "600" in the CLI means 600 * 1000 = 600,000 bps or 0.6 Mbps.
See also
--bandwidth and --startrate
fc::Control::detectApproximateUploadSpeed()
fc::Control::detectApproximateDownloadSpeed()
fc::ECommonBandwidth
fc::bps()
fc::Kbps()
fc::Mbps()
fc::Gbps()
Exceptions
fc::Exceptionif the bandwidth is out of range.

References fc::bps(), FC_WHERE, getMap(), and fc::k10_Gbps.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setBandwidth() [2/2]

fc::Options & fc::Options::setBandwidth ( const fc::ECommonBandwidth  full_bandwidth_bps,
const fc::ECommonBandwidth  slow_start_bandwidth_bps = fc::kZero_bps 
)
virtual

◆ setCongestionControl()

fc::Options & fc::Options::setCongestionControl ( const bool  enabled = false,
const int  aggression = 2 
)
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.

Note
Regardless of bandwidth available on the network, the maximum UDP transfer rate adjusted by congestion control will not be increased beyond the rate set in fc::Options::setBandwidth().
Parameters
[in]enabledSet 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]aggressionThe 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.
Warning
In situations where UDP congestion control is disabled, setting the desired maximum and start bandwidth rate in fc::Options::setBandwidth() is extremely important. Without UDP congestion control, transfer rates that are set too high will cause FC++ to flood the network, resulting in poor file transfers and degraded network performance. It is strongly recommended that UDP congestion control be enabled when using fc::kUdp mode.
CLI Example Description
fccl –congestioncontrol ... Enable UDP congestion control.
fccl –aggression 8 ... UDP congrestion control aggression level.
See also
--congestioncontrol
fc::Options::setBandwidth()
fc::Options::setMode()
Exceptions
fc::Exceptionif the aggression value is out of range.

References FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setEncoders()

fc::Options & fc::Options::setEncoders ( const int  number_of_encoders = 5)
virtual

Set the number of FileCatalyst server-based file encoders.

Note
This wont have any effect on TCP/FTP transfers, or when performing single-threaded UDP downloads.

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.

Since
v1119, November 2017

The number of encoders may also be impacted by calls to setMultiThreaded(). The default value for the number of server-side encoders as set in the FC++ API was changed from 3 to 5 in November 2017.

CLI Example Description
fccl –numencoders 5 ... The number of encoders to use on the FC server.
See also
--multithread and --numencoders
fc::Options::setMultiThreaded()
Parameters
[in]number_of_encodersMust be between 1 and 30.
Exceptions
fc::Exceptionif the number of encoders is out of range.

References FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setSocketOptions()

fc::Options & fc::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 
)
virtual

Set socket-based options.

Parameters
[in]socket_buffer_size_in_KiBis 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_enableddetermines whether keepalive probes are enabled on the TCP control channel. This is mapped to SO_KEEPALIVE in SOL_SOCKET.
[in]keepalive_interval_in_secondssets 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_probessets 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.
Note
Calling this method with a buffer size of zero forces FC++ to use the relatively small OS-defined socket buffers, without making any attempts to use a custom larger buffer size. While this is the most compatible option, the default OS network buffers for udp are typically so small that this is very likely to negatively affect FC++ performance.
Warning
On modern Linux kernels (>= 2.6.x), the maximum socket receive and transmit buffer sizes are limited to approximately 200 KiB. These maximum values are known as /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.
CLI Example Description
fccl –socketbuffersize 8192 ... Socket buffer size.
See also
fc::Options::setTimeout()
Tuning for Ubuntu
Exceptions
fc::Exceptionif the socket buffer size is out of range.

References FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setMd5Verification()

fc::Options & fc::Options::setMd5Verification ( const bool  enabled = false,
const int  mode = 0 
)
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.

CLI Example Description
fccl –verify ... Turn on MD5 verification.
fccl –verifymode 0 ... Verify mode 0 is the only mode supported by FC++.
See also
--verify
Parameters
[in]enabledDetermines if the post-transfer md5 checksum is enabled.
[in]modeMust be zero.
Exceptions
fc::Exceptionif the MD5 verification mode is non-zero.

References FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setEncryption()

fc::Options & fc::Options::setEncryption ( const bool  enable_TCP_SSL = false,
const bool  enable_UDP_AES = true 
)
virtual

Toggle control channel and data channel encryption.

Parameters
[in]enable_TCP_SSLcontrols 2 different settings:
  • Encryption of the control channel.
  • Encryption of the data channel when the mode is fc::kTcp.
[in]enable_UDP_AESapplies 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.
Note
  • If toggling the state of encryption, the TCP port number may also need to be changed.
  • Transfer performance is greatly influenced by encryption. This can be offset by enabling multi-thread support when using UDP upload or UDP download.
  • By default, UDP download is single-threaded which allows it to run in extreme low-memory environments. To obtain better performance, it is recommended that multi-thread support is enabled.
CLI Example Description
fccl –ssl ... Enable SSL encryption on the TCP control channel.
fccl –noaes ... Disable AES encryption on the UDP data channel.
See also
--ssl and --port
fc::Options::setFtpServer()
fc::Options::setMultiThreaded()
Here is the caller graph for this function:

◆ setSslHandshake()

fc::Options & fc::Options::setSslHandshake ( const fc::ESslHandshakeMode  ssl_handshake_mode = fc::kSslAutoDetect)
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.

Parameters
[in]ssl_handshake_modeThis must be set to fc::kSslFullHandshake or fc::kSslAutoDetect when connecting to File Catalyst servers.
Here is the caller graph for this function:

◆ setLocaldir()

fc::Options & fc::Options::setLocaldir ( const std::string &  local_directory = ".")
virtual

Base path used when accessing local files.

This path will be used only when files are specified using relative filenames.

CLI Example Description
fccl –localdir ../backups ... Set the default local directory.
See also
setRemotedir()
Here is the caller graph for this function:

◆ setRemotedir()

fc::Options & fc::Options::setRemotedir ( const std::string &  remote_directory = "/")
virtual

Base path used when accessing remote files.

This path will be used only when files are specified using relative filenames.

CLI Example Description
fccl –remotedir /incoming ... Set the default remote directory.
See also
setLocaldir()
Here is the caller graph for this function:

◆ setTransferResume()

fc::Options & fc::Options::setTransferResume ( const bool  enabled = false,
const int  md5_chunk_size_in_KiB = 16384 
)
virtual

Toggle support for resuming incomplete partial file transfers.

Parameters
[in]enabledDetermines if support for resuming transfers is supported.
[in]md5_chunk_size_in_KiBIf 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.

Note
Files smaller than 1 KiB in size will always be fully transfered if the MD5 checksum fails.
CLI Example Description
fccl –autoresume ... Enable resumption of partial file transfers.
Exceptions
fc::Exceptionif the MD5 chunk size is out of range.

References FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setOverwrite()

fc::Options & fc::Options::setOverwrite ( const bool  overwrite = false)
virtual

Toggle whether destination files can be overwritten.

CLI Example Description
fccl –overwrite ... Enable file overwriting.
fccl –donotoverwrite ... Disable file overwriting. This is the default value.
Here is the caller graph for this function:

◆ setMultiThreaded()

fc::Options & fc::Options::setMultiThreaded ( const bool  multi_threaded = true,
const int  count = 3 
)
virtual

Toggle whether multiple threads are used for UDP transfers.

Parameters
[in]multi_threadedis only used with udp-mode transfers.
[in]countis only used when multi_threaded has been set to true. Must be between 1 and 40.
Note
  • UDP downloads can be single-threaded or multi-threaded. Enabling multi-threaded downloads can achieve better transfer rates, but consumes more memory than single threaded transfers due to pre-allocation of file and memory buffers.
  • UDP uploads are always multi-threaded, but this call determines the number of additional encryption threads used by UDP uploads if SSL and AES encryption have been enabled.
  • TCP/FTP transfers (both upload and download) are never multi-threaded, even when this option has been set.
Since
v1119, November 2017

Enabling multi-threading will also transparently set the number of server-side encoders if the number of encoders is lower than the number of client-side threads. A call to setEncoders() can be made after setMultiThreaded() if a specific smaller number of server-side encoders is desired. For example, attempting to call this:

fc::Options options;
options.setEncoders(3);
options.setMultiThreaded(true, 5);

...will instead behave as if it had been called like this:

fc::Options options;
options.setMultiThreaded(true, 5);
options.setEncoders(7); // server-side encoders now default to client-side threads + 2

Unless advised otherwise, you should always keep the number of server-side encoders greater than the number of client-side threads.

CLI Example Description
fccl –multithread 3 ... Enable multithreading and set the number of extra threads. As of v1119, this would also transparently set the number of encoders.
See also
--multithread and --numencoders
fc::Options::setEncryption()
fc::Options::setEncoders()
Exceptions
fc::Exceptionif the thread count is out of range.

References FC_WHERE, getMap(), and setEncoders().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setRetries()

fc::Options & fc::Options::setRetries ( const int  count = 0,
const int  wait_period_in_seconds = 30 
)
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.

CLI Example Description
fccl –retry 3 ... Enable retries and set the count.
fccl –waitretry 30 ... Time to wait between retries.
Parameters
[in]countMust be between 1 and 99.
[in]wait_period_in_secondsMust be between 1 and 86400 (24 hours).
Exceptions
fc::Exceptionif the retry count is out of range.
fc::Exceptionif the retry pause length is out of range.

References FC_WHERE, and getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setTrace()

fc::Options & fc::Options::setTrace ( const bool  enabled = false)
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.

Warning
Trace messages have a negative impact on performance. This option should be kept off (the default value) unless trace messages are required for debugging purposes.
CLI Example Description
fccl –trace ... Enable trace.

References output_log_directory.

Here is the caller graph for this function:

◆ setLogFileOutputDir()

fc::Options & fc::Options::setLogFileOutputDir ( const std::string &  dir = "")
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().

Note
If both fc::Options::setLogFileOutputDir() and fc::Exception::createLogFile() are called, then the output directory should be set prior to creating the log file. Otherwise, the log file may possibly be created in the wrong directly, and wont be seen when fc::Exception::init() is called.
fc::Options options;
options.setLogFileOutputDir( "/var/log" );
options.setUsernameAndPassword( "bob", "secret" );
options.setFtpServer( ... );

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

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getLogFileOutputDir()

fc::Local fc::Options::getLogFileOutputDir ( void  )
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.

Here is the caller graph for this function:

◆ setTmpFilenames()

fc::Options & fc::Options::setTmpFilenames ( const bool  enabled = false,
const std::string &  suffix = ".tmp",
const std::string &  prefix = "" 
)
virtual

When uploading or downloading files, sometimes the target filename should not be overwritten or made available until the transfer has finished successfully.

This can be done by enabling temporary filenames. The FC++ client gives the file a temporary filename and then renames it after the transfer has successfully finished.

Note
The temporary filename prefix and suffix is sanitized to remove characters such as \ and /. This is to ensure the temporary file is stored in the same directory as the eventual target, and that the file can be easily accessed to be renamed once the transfer has finished.
CLI Example Description
fccl –usetempname ... Enable temporary filenames.
fccl –tmpmode 1 0=use prefix, 1=use suffix

References fc::SummaryLog::add().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setSummaryLogging()

fc::Options & fc::Options::setSummaryLogging ( const bool  enabled = false)
virtual

Write a summary log.

CLI Example Description
fccl –summary ... Enable summary logging.
See also
fc::SummaryLog

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