API Documentation

File Transfer

The PolySync File Transfer API.

Usage #include <PolySyncFileTransfer.hpp>

FileTransferOptions

The FileTransferOptions class is a set of options that are available for a file transfer operation.

FileTransferOptions::FileTransferOptions ( … )

This will construct a set of options used for file transfer operations.

Parameters
in/out type name description
in ps_guid sourceGuid The GUID of the source node with access to the file.
in const std::string & sourcePath The absolute path of the source file.
in ps_guid destinationGuid The GUID of the destination node with access to the file destination.
in const std::string & destinationPath The absolute path of the file destination.
in uint32_t chunkSize chunkSize = PSYNC_FILE_TRANSFER_DEFAULT_CHUNK_SIZE The size of pieces the file should be broken up into for file transfer. [bytes]
in uint32_t interChunkDelay interChunkDelay = PSYNC_FILE_TRANSFER_DEFAULT_CHUNK_DELAY The delay time between the transmission and reception of each file chunk. [microseconds]
in bool requireHash requireHash = false Flag indicating if the file transfer should use a file hashing mechanism as an additional integrity guarantee. Largely unnecessary for most file transfer operations.

FileTransferOptions::FileTransferOptions ( … )

The convenience constructor for building from ps_file_transfer_options.

Parameters
in/out type name description
in const ps_file_transfer_options * const options The input C structure to be copied.

virtual FileTransferOptions::~FileTransferOptions ( )

FileTransferOptions::operator== ( … ) const

Boolean comparison between file transfer option source/destination GUIDs and file paths.

Parameters
in/out type name description
in const FileTransferOptions & rhs Other options being compared against.
Returns
  • bool

FileTransferOptions::getSourceGuid ( ) const

This will get the source GUID from the transfer options.

Returns

FileTransferOptions::getDestinationGuid ( ) const

This will get the destination GUID from the transfer options.

Returns

FileTransferOptions::setSourceGuid ( … )

This will set the source GUID for the transfer options.

Parameters
in/out type name description
in ps_guid sourceGuid The GUID to be set as source.

FileTransferOptions::setDestinationGuid ( … )

This will set the destination GUID for the transfer options.

Parameters
in/out type name description
in ps_guid destinationGuid The GUID to be set as destination.

FileTransferOptions::getSourcePath ( ) const

This will get the absolute path to the source file for the transfer options.

Returns
  • const std::string &

FileTransferOptions::getDestinationPath ( ) const

This will get the absolute path to the destination file for the transfer options.

Returns
  • const std::string &

FileTransferOptions::setSourcePath ( … )

This will set the absolute path to the source file for the transfer options.

Parameters
in/out type name description
in const std::string & sourcePath The absolute path to the source file

FileTransferOptions::setDestinationPath ( … )

This will set the absolute path to the destination file for the transfer options.

Parameters
in/out type name description
in const std::string & destinationPath The absolute path to the destination path.

FileTransferOptions::getChunkSize ( ) const

This will get the chunk size in bytes for the file transfer options.

Returns
  • uint32_t

FileTransferOptions::getInterChunkDelay ( ) const

This will get the inter chunk delay in microseconds for the file transfer options.

Returns

FileTransferOptions::hashRequired ( ) const

This will check if the options will require file hash integrity checks during the transfer.

Returns
  • bool

FileTransferOptions::setChunkSize ( … )

This will set the chunk size in bytes for the file transfer options.

Parameters
in/out type name description
in uint32_t chunkSize The new size of file transfer chunks in bytes.

FileTransferOptions::setInterChunkDelay ( … )

This will set the inter chunk delay in microseconds for the file transfer options.

Parameters
in/out type name description
in ps_timestamp interChunkDelay The new inter chunk delay. [microseconds]

FileTransferOptions::setHashRequired ( … )

Set this if the options will require file hash integrity checks during the transfer.

Parameters
in/out type name description
in bool hashRequired If true, then file hash will be used to check transfer integrity.

FileTransferOptions::to_ps_file_transfer_options ( ) const

This will convert to the equivalent C type.

Returns

FileTransferState

The FileTransferState class is a summary of the state of an active file transfer.

FileTransferState::FileTransferState ( … )

This will construct a representation of a file transfer’s state.

Parameters
in/out type name description
in uint32_t currentChunkId = 0 The identifier of the file chunk that is currently being transferred. Zero is invalid.
in uint32_t totalChunks = 0 The total chunk count of the transfer.
in uint64_t currentChunkOffset = 0 The current byte offset of the transferring file.
in ps_dtc dtc = DTC_NONE The current error state of the transfer.

FileTransferState::FileTransferState ( … )

This will construct a representation of a file transfer’s state from the C type.

Parameters
in/out type name description
in const ps_file_transfer_state * const state The provided C type.

FileTransferState::getCurrentChunkId ( ) const

This will get the current chunk ID in file transfer.

Returns
  • uint32_t

FileTransferState::getTotalChunks ( ) const

This will get total count of chunks in file transfer.

Returns
  • uint32_t

FileTransferState::getCurrentChunkOffset ( ) const

This will get the current chunk offset in the file transfer in bytes.

Returns
  • uint64_t

FileTransferState::getDtc ( ) const

Returns

FileTransferState::setCurrentChunkId ( … )

This will set the current chunk ID in file transfer.

Parameters
in/out type name description
in uint32_t currentChunkId The current chunk ID, starting with 1.

FileTransferState::setTotalChunks ( … )

This will set the total count of chunks in file transfer.

Parameters
in/out type name description
in uint32_t totalChunks The total chunk count.

FileTransferState::setCurrentChunkOffset ( … )

This will set the current chunk offset in the file transfer in bytes.

Parameters
in/out type name description
in uint64_t currentChunkOffset The current file chunk byte offset.

FileTransferState::setDtc ( … )

Parameters
in/out type name description
in ps_dtc dtc The diagnostic code of the file transfer state.

FileTransferSubscription

The FileTransferSubscription class is a subscription to a file transfer operation.

FileTransferState updates are provided via FileTransferCallback.

FileTransferSubscription::FileTransferSubscription ( … )

This will construct a subscription using the same options that will be used to start the file transfer operation.

Parameters
in/out type name description
in const FileTransferOptions & options The options used to start the transfer.

FileTransferSubscription::getTransferOptions( ) const

This will get the options used when creating the subscription.

Returns

onProgress ( … ) const

A callback interface invoked by the active file transfer to which the subscription has registered.

Parameters
in/out type name description
in const FileTransferState & state
in const FileTransferOptions & options

onEnd ( … ) const

A callback interface that will be invoked by the active file transfer to which the subscription has registered.

Parameters
in/out type name description
in const FileTransferState & state
in const FileTransferOptions & options

FileTransferHandler

The FileTransferHandler class is the main interface to file transfer operations.

FileTransferHandler::FileTransferHandler ( )

This will construct a handler of file transfer operations.

FileTransferHandler::start ( … )

This will start a file transfer operation based on provided options.

Parameters
in/out type name description
in const FileTransferOptions & transferOptions The options providing the details of the file transfer operation to start.
Returns
  • void

FileTransferHandler::start ( … )

This will start a queue of file transfer operations based on provided options.

Parameters
in/out type name description
in const std::vector< FileTransferOptions > & transferOptions A vector of options providing details of multiple file transfers that will be executed in sequence.
Returns
  • void

FileTransferHandler::abort ( … ) const

This will abort all file transfer operations matching the provided options.

Parameters
in/out type name description
in const FileTransferOptions & transferOptions The options matching the file transfer that will be aborted.
Returns
  • void

FileTransferHandler::waitForAll ( … ) const

This will wait for all of the file transfer operations to be completed.

Parameters
in/out type name description
in ps_timestamp timeout = 0 Duration to wait for all file transfer operations to complete. Timeout of zero indicates indefinite waiting.
Returns
  • void
Throws
  • DTCException - If all file transfer operations are not completed within timeout

FileTransferHandler::attachSubscription ( … )

This will attach a file transfer subscription.

If a file transfer matching the subscription options receives status updates, then the subscription callback will be notified.

Parameters
in/out type name description
in std::shared_ptr< FileTransferSubscription > subscription The subscription to be registered.
Returns
  • void

FileTransferHandler::detachSubscription ( … )

This will detach a file transfer subscription.

Parameters
in/out type name description
in std::shared_ptr< FileTransferSubscription > subscription The subscription to be unregistered.
Returns
  • void