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 ()
	Destructor. More...

	Options ()
	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 ()
	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=5)
	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=".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 Options &	setSummaryLogging (const bool enabled=false)
	Write a summary log. More...

Static Public Member Functions
static fc::Local	getLogFileOutputDir ()
	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 ( )

virtual

Destructor.

◆ Options() [1/2]

fc::Options::Options ( )

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 ( )

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.

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] 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::formatBytesIEC(), fc::formatTimeDuration(), fc::formatTransferRate(), fc::kFtp, fc::kSslAutoDetect, fc::kSslFullHandshake, fc::kSslSessionReuse, fc::kUdp, password, and username.

Here is the call 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] 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.

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::Exception	if the server TCP port is invalid.
fc::Exception	if the server's hostname cannot be resolved.

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

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.

References password, and username.

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]	cm	Must 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::Exception	if the transfer mode is not supported.
fc::Exception	if the connection mode is not supported.

References FC_WHERE, fc::kFtp, fc::kPassive, and fc::kUdp.

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.

◆ 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] timeout Must be between 2 and 300 seconds.

Exceptions

fc::Exception if the socket timeout is out of range.

References FC_WHERE.

◆ 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_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.

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::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.

◆ 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_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.

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::Exception if the bandwidth is out of range.

References fc::bps(), FC_WHERE, 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

Similar to fc::Options::setBandwidth( const uint64_t, const uint64_t ) but accepts fc::ECommonBandwidth enum as parameters.

See also: fc::Options::setBandwidth( const uint64_t, const uint64_t ); fc::ECommonBandwidth; fc::bps()

References fc::bps().

Here is the call graph for this function:

◆ 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]	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.

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::Exception if the aggression value is out of range.

References FC_WHERE.

◆ 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_encoders Must be between 1 and 30.

Exceptions

fc::Exception if the number of encoders is out of range.

References FC_WHERE.

◆ 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_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.

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::Exception if the socket buffer size is out of range.

References FC_WHERE.

◆ 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]	enabled	Determines if the post-transfer md5 checksum is enabled.
[in]	mode	Must be zero.

Exceptions

fc::Exception if the MD5 verification mode is non-zero.

References FC_WHERE.

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_SSL	controls 2 different settings: Encryption of the control channel. Encryption of the data channel when the mode is fc::kTcp.
[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.

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()

◆ 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_mode This must be set to fc::kSslFullHandshake or fc::kSslAutoDetect when connecting to File Catalyst servers.

◆ 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()

◆ 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()

◆ 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]	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.

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::Exception if the MD5 chunk size is out of range.

References FC_WHERE.

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_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.

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::Exception if the thread count is out of range.

References FC_WHERE.

◆ 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]	count	Must be between 1 and 99.
[in]	wait_period_in_seconds	Must be between 1 and 86400 (24 hours).

Exceptions

fc::Exception	if the retry count is out of range.
fc::Exception	if the retry pause length is out of range.

References FC_WHERE.

◆ 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.

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" );
fc::Exception::createLogFile( true );
options.setUsernameAndPassword( "bob", "secret" );
options.setFtpServer( ... );

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getLogFileOutputDir()

fc::Local fc::Options::getLogFileOutputDir ( )

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:

◆ 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:

src/publicInclude/FCOptions.hpp
src/libfc/FCOptions.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Options()

◆ Options() [1/2]

◆ Options() [2/2]

Member Function Documentation

◆ reset()

◆ getMap()

◆ getStr()

◆ setFtpServer()

◆ setUsernameAndPassword()

◆ setMode()

◆ setClientId()

◆ setTimeout()

◆ setLimits()

◆ setBandwidth() [1/2]

◆ setBandwidth() [2/2]

◆ setCongestionControl()

◆ setEncoders()

◆ setSocketOptions()

◆ setMd5Verification()

◆ setEncryption()

◆ setSslHandshake()

◆ setLocaldir()

◆ setRemotedir()

◆ setTransferResume()

◆ setOverwrite()

◆ setMultiThreaded()

◆ setRetries()

◆ setTrace()

◆ setLogFileOutputDir()

◆ getLogFileOutputDir()

◆ setTmpFilenames()

◆ setSummaryLogging()