API Documentation

File Transfer

Usage #include <polysync_file_transfer.h>

Functions

psync_file_transfer_init ( … )

This will initialize a file transfer context.

Parameters
in/out type name description
out ps_file_transfer_handle * const transfer_handle File transfer context to be initialized.
in const ps_node_ref node_ref The reference to the node that will be used to send and receive messages required for file transfer operations.
Returns

psync_file_transfer_release ( … )

This will release the file transfer context.

Parameters
in/out type name description
in ps_file_transfer_handle * const transfer_handle The file transfer context to be released.
Returns

psync_file_transfer_wait_for_all ( … )

This will suspend execution in the calling thread until all transfers have ended.

Parameters
in/out type name description
in const ps_file_transfer_handle transfer_handle The same file transfer context that was previously used to start transfers.
Returns
  • DTC Code:
    • DTC_NONE - If success
    • DTC_USAGE - If invalid input

psync_file_transfer_wait_for_all_timed ( … )

This will suspend execution in the calling thread until all transfers have ended or timeout expires.

Parameters
in/out type name description
in const ps_file_transfer_handle transfer_handle The file transfer context used to start transfers.
in const ps_timestamp timeout Maximum time to wait for all transfers to end. [microseconds]
Returns
  • DTC Code:
    • DTC_NONE - If success
    • DTC_INTR - If waiting interrupted by timeout before all transfers ended
    • DTC_USAGE - If invalid input

psync_file_transfer_start ( … )

This will start a file transfer between two nodes.

Parameters
in/out type name description
in const ps_file_transfer_handle transfer_handle The local file transfer context.
in const ps_file_transfer_options * const options Set of options for the file transfer. source_guid, destination_guid, source_path, and destination_path are required.
Returns
  • DTC Code:
    • DTC_NONE - If success
    • DTC_USAGE - If invalid input

psync_file_transfer_abort ( … )

This will abort the active file transfers to a ps_guid.

Parameters
in/out type name description
in const ps_file_transfer_handle transfer_handle The local file transfer context.
in const ps_file_transfer_options * const destination_path A NULL terminated string of the destination path for the transfers to be aborted. If NULL, then field will be ignored and all transfers with the provided ps_guid will be aborted.
in destination_guid ps_guid of the host receiving the transfer(s) to be aborted.
Returns

psync_file_transfer_ext_msg_handler ( … )

This will provide the default handling of ps_file_transfer_ext_msg.

Parameters
in/out type name description
in const ps_file_transfer_handle transfer_handle File transfer context that may be modified by creating/removing threads if needed to respond to the request.
in const ps_file_transfer_ext_msg * const transfer_msg The ps_file_transfer_ext_msg to be handled.
Returns
  • DTC Code:
    • DTC_NONE - If success
    • DTC_USAGE - If invalid input

psync_file_ext_msg_handler ( … )

This will provide the default handling of ps_file_ext_msg.

Parameters
in/out type name description
in const ps_file_transfer_handle transfer_handle File transfer context that passes the ps_file_ext_msg data to corresponding active file transfer.
in const ps_file_ext_msg * const file_msg ps_file_ext_msg to be handled.
Returns

psync_file_transfer_register_default_handling ( … )

This will register the default handling of ps_file_ext_msg and ps_file_transfer_ext_msg.

Parameters
in/out type name description
in const ps_file_transfer_handle transfer_handle File transfer context that will be registered to handle file transfer messages in the default behavior.
Returns

psync_file_transfer_unregister_default_handling ( … )

This will unregister the default handling of ps_file_ext_msg and ps_file_transfer_ext_msg.

Parameters
in/out type name description
in const ps_file_transfer_handle transfer_handle File transfer context that will be unregistered from handling file transfer messages in the default behavior.
Returns
  • DTC Code:
    • DTC_NONE - If success
    • DTC_USAGE - If invalid input

Macros

PSYNC_FILE_TRANSFER_DEFAULT_CHUNK_DELAY

Value Description
1000 The default delay in microseconds between chunk operations.

PSYNC_FILE_TRANSFER_DEFAULT_CHUNK_SIZE

Value Description
32768 The default chunk size in bytes of ps_file_ext_msg data.

Structures

ps_file_transfer_options

The configuration options to be passed to ps_file_transfer_start.

Data Type Name Description
ps_guid source_guid GUID of the node providing the file.
ps_guid destination_guid GUID of the node receiving the file.
char[ PSYNC_FILE_TRANSFER_PATH_LENGTH ] source_path Absolute file path of the source file.
char[ PSYNC_FILE_TRANSFER_PATH_LENGTH ] destination_path Absolute file path of the destination file.
uint32_t chunk_size Size of the file data chunks in bytes.
ps_timestamp inter_chunk_delay Delay time between chunk operations in microseconds. If zero, then it defaults to PSYNC_FILE_TRANSFER_DEFAULT_CHUNK_DELAY.
uint8_t require_hash Flag indicating whether transfer should compute and compare the file’s hash on both sides of the transfer.
psync_file_transfer_callback on_progress Callback providing periodic progress information on the caller.
psync_file_transfer_callback on_end Callback providing a notification of the file transfer ending.
void * user_data A pointer to user data that will be passed to all psync_file_transfer_callback options.
ps_file_transfer_options * next Pointer to options for the next file transfer operation. This is usually NULL but allows optional, sequential transfers.

ps_file_transfer_state

Data Type Name Description
ps_file_transfer_options * transfer_options Configuration options of the file transfer.
uint32_t current_chunk_id Current data chunk identifier. Value zero means invalid. The first chunk will have a value of one.
uint32_t total_chunks Total number of file data chunks.
uint64_t current_chunk_offset Offset of the most recent file chunk in bytes.
ps_dtc dtc Current error code status of the file transfer.

Typedefs

ps_file_transfer_handle

Data Type Description
void * A pointer to the file transfer context used to handle all of the file transfer operations.

psync_file_transfer_callback

This is a convenient typedef of the function signature required for file transfer callbacks. This type acts to provide optional feedback to the caller of file transfer operations. Any operation that accepts ps_file_transfer_options may take such optional callback functions. For instance, ps_file_transfer_start accepts optional arguments, provided by the ps_file_transfer_options type in its on_progress and on_end fields.

Parameters
in/out type description
in const ps_file_transfer_state * The current state of the file transfer.
in void * User provided data from the user_data field found in ps_file_transfer_options, which is used to start the transfer.
Returns
  • void