fc::TransferStats Class Reference

File transfer statistics. More...

#include <FCTransferStats.hpp>

Collaboration diagram for fc::TransferStats:

Public Types
enum	EState {   kInvalid = -1,   kUnknown = 0,   kMd5InProgress = 10,   kMd5Success,   kMd5Failed,   kMd5Skipped,   kPending = 20,   kTransferStarted,   kTransferFinished,   kTransferFailed,   kFull = 30,   kPartial,   kSkippedMD5,   kSkippedFileExists }
	Used in several locations to indicate the state of the file transfer. More...

Public Member Functions
	TransferStats (void)
	Constructor. More...
TransferStats &	clear (const bool all=true)
	Clear most or all of the transfer statistics. More...
TransferStats &	operator+= (const TransferStats &rhs)
	Combine transfer statistics to get statistics over several files. More...
fc::StrMap	getMap (const std::string &header="") const
	Format all the transfer statistics as easy-to-read text strings, and store into a map of strings. More...
std::string	getStr (const std::string &header="", const bool all=false) const
	Similar to getMap(), but append all items to create a single multi-line text string to display for debug purposes. More...
fc::StrMap &	add_to_map (fc::StrMap &m, const std::string &header="") const
	Get the map entries – similar to getmap() – but instead of returning a new map, add the entries to a pre-existing map. More...
fc::Local	target_local_filename (void) const
	Returns the local filename which should be used. More...
fc::Remote	target_remote_filename (void) const
	Returns the remote filename which should be used. More...
bool	tmp_filename_is_disabled (void) const
	Determine if this file stats object has the necessary filename information to use a temporary filename during transfer. More...
bool	tmp_filename_is_enabled (void) const
	Determine if this file stats object has the necessary filename information to use a temporary filename during transfer. More...

Public Attributes
EState	md5
	State of the MD5 verification. More...
EState	transfer
	State of the file transfer. More...
EState	type
	The type of transfer. More...
fc::Local	localFilename
fc::Remote	remoteFilename
	Including the path. More...
std::chrono::high_resolution_clock::time_point	timeTransferBegan
	The time when the file transfer began. More...
std::chrono::high_resolution_clock::time_point	timePreviousBlockFinished
	The time when the last block completed. More...
std::chrono::high_resolution_clock::duration	timeRemaining
	The amount of time left at the current transfer rate. More...
std::chrono::high_resolution_clock::time_point	timeTransferFinished
	The time when the transfer completed. More...
uint64_t	payloadBytesTransferred
	The number of payload bytes. More...
uint64_t	payloadBytesExpected
	The total size being transferred. More...
uint64_t	payloadBytesSkipped
	The number of bytes that were skipped due to a successful auto-resume of a partial transfer. More...
uint64_t	bitsPerSecondAverageTransferRate
	Transfer rates measured in bits per second. More...
uint64_t	bitsPerSecondImmediateTransferRate
	Transfer rates measured in bits per second. More...
uint64_t	blocksCompleted
	The number of completed transfer blocks. More...
uint64_t	blocksRemaining
	The number of transfer blocks remaining. More...
uint64_t	packetsReceived
	The total number of packets received from the server. More...
uint64_t	packetsSent
	The total number of packets sent to the server (client-side overhead). More...
uint64_t	duplicatePacketDropped
	The total number of payload packets dropped because we received a duplicate from the server. More...
uint64_t	requestRetransmit
	The total number of client-side requests made to the server to transmit or retransmit a specific packet. More...
uint64_t	ackPacketsReceived
	The total number of ack packets. More...
uint64_t	dataPacketsReceived
	The total number of data packets received. More...
uint64_t	echoPacketsReceived
	The total number of echo packets received. More...
uint64_t	metricsPacketsReceived
	The total number of metric packets received. More...
uint64_t	metricsPacketsSent
	The total number of metric packets sent. More...
uint64_t	packetLossEvent
	The total number of data packet loss events. More...
uint64_t	unitSize
	The unit (packet) size. More...
uint64_t	blockSize
	The block size. More...
bool	encrypted
	Whether the transfer was encrypted using TCP+SSL or UDP+AES. More...
bool	upload
	Whether the transfer was an upload or a download. More...
std::string	localMd5
	May not be set if MD5 is disabled. More...
fc::Local	temporaryLocalFilename
	Temporary filename used during transfer. More...

Detailed Description

File transfer statistics.

Note

Not all of the statistics are available for all transfer types.

Warning

There are no thread locks to the transfer stats. Some of these values will periodically update during active file transfers. If this is a concern, please see fc::Control::setStatsCallback() instead.

Also see fc::GlobalStateAndStats which contains a std::map of TransferStats.

While this class initially contained a few simple statistics (thus the name) it has evolved to function as a transfer record, containing everything needed for the FC object to manage multiple sequential file transfers through the use of the std::map known as TransferStatsMap.

Member Enumeration Documentation

enum fc::TransferStats::EState

Used in several locations to indicate the state of the file transfer.

See also

fc::TransferStats::md5

fc::TransferStats::transfer

fc::TransferStats::type

fc::formatTransferStatsEState()

Enumerator
kInvalid
kUnknown
kMd5InProgress	TransferStats::md5 MD5 verification has started; see fc::Options::setMd5Verification()
kMd5Success	TransferStats::md5 MD5 verification was successful
kMd5Failed	TransferStats::md5 MD5 verification failed
kMd5Skipped	TransferStats::md5 file transfer was skipped since MD5 checksum indicates no changes; see fc::Options::setTransferResume()
kPending	TransferStats::transfer file is scheduled for transfer, but transfer has not yet started; see fc::Control::prepareSingleFile() or fc::Control::prepareRecursiveDir()
kTransferStarted	TransferStats::transfer file transfer is in progress
kTransferFinished	TransferStats::transfer indicates the transfer was successful
kTransferFailed	TransferStats::transfer transfer did not complete
kFull	TransferStats::type full transfer (entire file was sent or received)
kPartial	TransferStats::type only part of the file needed to be transferred (transfer was resumed); see fc::Options::setTransferResume()
kSkippedMD5	TransferStats::type the entire file was skipped (md5 matched); see fc::Options::setTransferResume()
kSkippedFileExists	TransferStats::type the entire file was skipped (overwrite mode is disabled); see fc::Options::setOverwrite()

Constructor & Destructor Documentation

fc::TransferStats::TransferStats

(

void

)

Constructor.

References clear().

Here is the call graph for this function:

Member Function Documentation

fc::TransferStats & fc::TransferStats::clear

(

const bool

all = true

)

Clear most or all of the transfer statistics.

Parameters

[in]

all

When set to false the values localFilename, remoteFilename, temporaryLocalFilename, temporaryRemoteFilename, and payloadBytesExpected are preserved (not cleared).

References ackPacketsReceived, bitsPerSecondAverageTransferRate, bitsPerSecondImmediateTransferRate, blocksCompleted, blockSize, blocksRemaining, dataPacketsReceived, duplicatePacketDropped, echoPacketsReceived, encrypted, kUnknown, localFilename, localMd5, md5, metricsPacketsReceived, metricsPacketsSent, packetLossEvent, packetsReceived, packetsSent, payloadBytesExpected, payloadBytesSkipped, payloadBytesTransferred, remoteFilename, requestRetransmit, temporaryLocalFilename, timePreviousBlockFinished, timeRemaining, timeTransferBegan, timeTransferFinished, transfer, type, unitSize, and upload.

Here is the caller graph for this function:

fc::TransferStats & fc::TransferStats::operator+=

(

const TransferStats &

rhs

)

Combine transfer statistics to get statistics over several files.

References ackPacketsReceived, bitsPerSecondAverageTransferRate, bitsPerSecondImmediateTransferRate, blocksCompleted, blockSize, blocksRemaining, dataPacketsReceived, duplicatePacketDropped, echoPacketsReceived, encrypted, kUnknown, localFilename, localMd5, md5, metricsPacketsReceived, metricsPacketsSent, packetLossEvent, packetsReceived, packetsSent, payloadBytesExpected, payloadBytesSkipped, payloadBytesTransferred, remoteFilename, requestRetransmit, temporaryLocalFilename, timePreviousBlockFinished, timeRemaining, timeTransferBegan, timeTransferFinished, transfer, type, unitSize, and upload.

fc::StrMap fc::TransferStats::getMap

(

const std::string &

header = ""

)

const

Format all the transfer statistics as easy-to-read text strings, and store into a map of strings.

Parameters

[in]

header

Text string to include before every line.

See also

fc::TransferStats::getStr()

References ackPacketsReceived, bitsPerSecondAverageTransferRate, bitsPerSecondImmediateTransferRate, blocksCompleted, blockSize, blocksRemaining, dataPacketsReceived, duplicatePacketDropped, echoPacketsReceived, encrypted, fc::formatBytesIEC(), fc::formatTimeDuration(), fc::formatTimeRecent(), fc::formatTransferRate(), fc::formatTransferStatsEState(), fc::Name::full(), localFilename, localMd5, md5, metricsPacketsReceived, metricsPacketsSent, packetLossEvent, packetsReceived, packetsSent, payloadBytesExpected, payloadBytesSkipped, payloadBytesTransferred, remoteFilename, requestRetransmit, temporaryLocalFilename, timePreviousBlockFinished, timeRemaining, timeTransferBegan, timeTransferFinished, tmp_filename_is_enabled(), transfer, type, unitSize, and upload.

Here is the call graph for this function:

Here is the caller graph for this function:

std::string fc::TransferStats::getStr	(	const std::string &	header = "",
		const bool	all = false
	)		const

Similar to getMap(), but append all items to create a single multi-line text string to display for debug purposes.

Parameters

[in]	header	Text string to include before every line.
[in]	all	Determines whether statistics with zero values are included.

See also

fc::TransferStats::getMap()

--showstats

For example:

fc::Control ftp(options);
ftp.upload( my_local_file );
const fc::TransferStats &stats = ftp.getMostRecentFileStats();
std::cout << stats.getStr("-> ") << std::endl;

...might result in output that looks like this:

-> Average transfer rate:             87.79 Mbps
-> Blocks completed:                  80
-> Bytes expected:                    150.00 MiB
-> Bytes transferred:                 150.71 MiB
-> DATA packets received:             103863
-> Duplicate packets:                 35
-> ...etc...

References getMap().

Here is the call graph for this function:

Here is the caller graph for this function:

fc::StrMap & fc::TransferStats::add_to_map	(	fc::StrMap &	m,
		const std::string &	header = ""
	)		const

Get the map entries – similar to getmap() – but instead of returning a new map, add the entries to a pre-existing map.

References getMap().

Here is the call graph for this function:

fc::Local fc::TransferStats::target_local_filename ( void  ) const

inline

Returns the local filename which should be used.

Normally, this is the same as the "normal" local filename. But when temporary transfer filename support is enabled, this will be different during downloads. Once the transfer has finished, the file is automatically renamed by FC++ from the temporary name to the expected name.

See also

fc::Options::setTmpFilenames()

Since

v0.7.1-1065, September 2016.

References fc::Name::empty(), localFilename, and temporaryLocalFilename.

Here is the call graph for this function:

Here is the caller graph for this function:

fc::Remote fc::TransferStats::target_remote_filename ( void  ) const

inline

Returns the remote filename which should be used.

Normally, this is the same as the "normal" remote filename. But when temporary transfer filename support is enabled, this will be different during uploads. Once the transfer has finished, the file is automatically renamed by FC++ from the temporary name to the expected name.

See also

fc::Options::setTmpFilenames()

Since

v0.7.1-1065, September 2016.

References fc::Name::empty(), and remoteFilename.

Here is the call graph for this function:

Here is the caller graph for this function:

bool fc::TransferStats::tmp_filename_is_disabled ( void  ) const

inline

Determine if this file stats object has the necessary filename information to use a temporary filename during transfer.

See also

fc::Options::setTmpFilenames()

Since

v0.7.1-1065, September 2016.

References fc::Name::empty().

Here is the call graph for this function:

Here is the caller graph for this function:

bool fc::TransferStats::tmp_filename_is_enabled ( void  ) const

inline

Determine if this file stats object has the necessary filename information to use a temporary filename during transfer.

See also

fc::Options::setTmpFilenames()

Since

v0.7.1-1065, September 2016.

References fc::bps(), fc::formatBytesIEC(), fc::formatBytesOldStyle(), fc::formatBytesSI(), fc::formatTimeDuration(), fc::formatTimeDuration2(), fc::formatTimeRecent(), fc::formatTimestamp(), fc::formatTimestamp2(), fc::formatTransferRate(), fc::formatTransferStatsEState(), tmp_filename_is_disabled(), and fc::to_time_t().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

EState fc::TransferStats::md5

State of the MD5 verification.

For example, see fc::TransferStats::kMd5InProgress.

See also

fc::TransferStats::localMd5

fc::TransferStats::remoteMd5

fc::formatTransferStatsEState()

fc::Options::setMd5Verification()

EState fc::TransferStats::transfer

State of the file transfer.

For example, see fc::TransferStats::kTransferStarted.

See also

fc::formatTransferStatsEState()

EState fc::TransferStats::type

The type of transfer.

For example, see fc::TransferStats::kSkippedFileExists.

See also

fc::formatTransferStatsEState()

std::string fc::TransferStats::localMd5

May not be set if MD5 is disabled.

Note

If partial transfers are enabled in the transfer options, then the local and remote MD5 checksum fields may contain just the partial MD5 and not the full MD5 of the entire file.

Since

December 2011.

See also

fc::TransferStats::remoteMd5

fc::TransferStats::md5

fc::Options::setMd5Verification()

fc::Local fc::TransferStats::localFilename

Including the path.

fc::Remote fc::TransferStats::remoteFilename

Including the path.

fc::Local fc::TransferStats::temporaryLocalFilename

Temporary filename used during transfer.

See also

fc::TransferStats::target_local_filename()

fc::TransferStats::target_remote_filename()

fc::Options::setTmpFilenames()

Since

v0.7.1-1065, September 2016.Temporary local filename prior to being renamed.

std::chrono::high_resolution_clock::time_point fc::TransferStats::timeTransferBegan

The time when the file transfer began.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

std::chrono::high_resolution_clock::time_point fc::TransferStats::timePreviousBlockFinished

The time when the last block completed.

Available when using:

• UDP download
• UDP upload

std::chrono::high_resolution_clock::duration fc::TransferStats::timeRemaining

The amount of time left at the current transfer rate.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

Note

This statistic doesn't reflect dropped UDP packets when using UDP upload or UDP download. Thus, the actual file transfer may take longer depending on network conditions. For a coarser counter that can be used to determine what percentage of a UDP transfer remains, see blocksCompleted and blocksRemaining.

Since

v743, December 2011.

std::chrono::high_resolution_clock::time_point fc::TransferStats::timeTransferFinished

The time when the transfer completed.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

uint64_t fc::TransferStats::payloadBytesTransferred

The number of payload bytes.

• On downloads: how many payload bytes have been received from the server.
• On uploads: how many payload bytes have been sent to the server.

Note

This includes bytes in payloadBytesSkipped.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

uint64_t fc::TransferStats::payloadBytesExpected

The total size being transferred.

Note

This does not include any bytes in payloadBytesSkipped.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

uint64_t fc::TransferStats::payloadBytesSkipped

The number of bytes that were skipped due to a successful auto-resume of a partial transfer.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

See also

fc::Options::setTransferResume()

Since

v0.7.1-974, September 2015.

uint64_t fc::TransferStats::bitsPerSecondAverageTransferRate

Transfer rates measured in bits per second.

This is the data rate at L7, and it does not reflect additional overhead from IP, TCP, UDP, or FileCatalyst headers.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

See also

fc::Options::setBandwidth()

Since

v743, December 2011.

uint64_t fc::TransferStats::bitsPerSecondImmediateTransferRate

Transfer rates measured in bits per second.

This is the data rate at L7, and it does not reflect additional overhead from IP, TCP, UDP, or FileCatalyst headers.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

See also

fc::Options::setBandwidth()

Since

v743, December 2011.

uint64_t fc::TransferStats::blocksCompleted

The number of completed transfer blocks.

Available when using:

• UDP download
• UDP upload

See also

fc::Options::setLimits()

uint64_t fc::TransferStats::blocksRemaining

The number of transfer blocks remaining.

Available when using:

• UDP download
• UDP upload

See also

fc::Options::setLimits()

uint64_t fc::TransferStats::packetsReceived

The total number of packets received from the server.

This includes both duplicates and overhead non-data packets. Available when using:

• UDP download
• UDP upload

uint64_t fc::TransferStats::packetsSent

The total number of packets sent to the server (client-side overhead).

Available when using:

• UDP download
• UDP upload

uint64_t fc::TransferStats::duplicatePacketDropped

The total number of payload packets dropped because we received a duplicate from the server.

Available when using:

• UDP download
• UDP upload

uint64_t fc::TransferStats::requestRetransmit

The total number of client-side requests made to the server to transmit or retransmit a specific packet.

Available when using:

• UDP download
• UDP upload

uint64_t fc::TransferStats::ackPacketsReceived

The total number of ack packets.

Available when using:

• UDP download
• UDP upload

uint64_t fc::TransferStats::dataPacketsReceived

The total number of data packets received.

Available when using:

• UDP download
• UDP upload

uint64_t fc::TransferStats::echoPacketsReceived

The total number of echo packets received.

Available when using:

• UDP download
• UDP upload

uint64_t fc::TransferStats::metricsPacketsReceived

The total number of metric packets received.

Available when using:

• UDP download
• UDP upload

Since

v842, March 2012.

uint64_t fc::TransferStats::metricsPacketsSent

The total number of metric packets sent.

Available when using:

• UDP download
• UDP upload

Since

v842, October 2014.

uint64_t fc::TransferStats::packetLossEvent

The total number of data packet loss events.

Available when using:

• UDP upload

Since

v794, October 2014.

uint64_t fc::TransferStats::unitSize

The unit (packet) size.

Available when using:

• UDP download
• UDP upload

See also

fc::Options::setLimits()

Since

v844, November 2014.

uint64_t fc::TransferStats::blockSize

The block size.

Available when using:

• UDP download
• UDP upload

See also

fc::Options::setLimits()

Since

v844, November 2014.

bool fc::TransferStats::encrypted

Whether the transfer was encrypted using TCP+SSL or UDP+AES.

Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

See also

fc::Options::setEncryption()

Since

v846, November 2014.

bool fc::TransferStats::upload

Whether the transfer was an upload or a download.

This is set to TRUE if uploaded, and FALSE if downloaded. Available when using:

• UDP download
• UDP upload
• FTP download
• FTP upload

Since

v1060, May 2016.

---

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

• src/publicInclude/FCTransferStats.hpp
• src/libfc/FCTransferStats.cpp