Overview

RPC client for running pw_transfer read and write data transfers.

Currently, a Client is capable of running transfers over a single RPC channel, processed on a shared TransferThread.

Classes
class	Handle

Public Types
using	CompletionFunc = Function< void(Status)>

Public Member Functions
	Client (rpc::Client &rpc_client, uint32_t channel_id, TransferThread &transfer_thread, size_t max_window_size_bytes, uint32_t extend_window_divisor=cfg::kDefaultExtendWindowDivisor)

	Client (rpc::Client &rpc_client, uint32_t channel_id, TransferThread &transfer_thread)

	Client (const Client &)=delete

	Client (Client &&)=delete

Client &	operator= (const Client &)=delete

Client &	operator= (Client &&)=delete

Result< Handle >	Read (uint32_t resource_id, stream::Writer &output, CompletionFunc &&on_completion, ProtocolVersion protocol_version, chrono::SystemClock::duration timeout=cfg::kDefaultClientTimeout, chrono::SystemClock::duration initial_chunk_timeout=cfg::kDefaultInitialChunkTimeout, uint32_t initial_offset=0u)

Result< Handle >	Read (uint32_t resource_id, stream::Writer &output, CompletionFunc &&on_completion, chrono::SystemClock::duration timeout=cfg::kDefaultClientTimeout, chrono::SystemClock::duration initial_chunk_timeout=cfg::kDefaultInitialChunkTimeout, uint32_t initial_offset=0u)

Result< Handle >	Write (uint32_t resource_id, stream::Reader &input, CompletionFunc &&on_completion, ProtocolVersion protocol_version, chrono::SystemClock::duration timeout=cfg::kDefaultClientTimeout, chrono::SystemClock::duration initial_chunk_timeout=cfg::kDefaultInitialChunkTimeout, uint32_t initial_offset=0u)

Result< Handle >	Write (uint32_t resource_id, stream::Reader &input, CompletionFunc &&on_completion, chrono::SystemClock::duration timeout=cfg::kDefaultClientTimeout, chrono::SystemClock::duration initial_chunk_timeout=cfg::kDefaultInitialChunkTimeout, uint32_t initial_offset=0u)

Status	set_extend_window_divisor (uint32_t extend_window_divisor)

constexpr Status	set_max_retries (uint32_t max_retries)

constexpr Status	set_max_lifetime_retries (uint32_t max_lifetime_retries)

constexpr void	set_protocol_version (ProtocolVersion new_version)

bool	has_read_stream () const

bool	has_write_stream () const

Friends
class	internal::TransferThread

Member Typedef Documentation

◆ CompletionFunc

using pw::transfer::Client::CompletionFunc = Function<void(Status)>

Callback invoked from the transfer thread when a transfer completes, receiving the overall status of the transfer.

Constructor & Destructor Documentation

◆ Client() [1/2]

pw::transfer::Client::Client	(	rpc::Client &	rpc_client,
		uint32_t	channel_id,
		TransferThread &	transfer_thread,
		size_t	max_window_size_bytes,
		uint32_t	extend_window_divisor = `cfg::kDefaultExtendWindowDivisor`
	)

inline

Initializes a transfer client on a specified RPC client and channel.

Transfer tasks are processed on the provided transfer_thread, which may be shared between a transfer client and service.

Parameters

[in]	rpc_client	RPC client over which transfer streams are opened.
[in]	channel_id	RPC channel ID on which transfers are run.
[in]	transfer_thread	Thread used to process transfer events.
[in]	max_window_size_bytes	Maximum amount of data in bytes to request at a time during a read transfer, unless told a more restrictive amount by the transfer's stream. This size should span multiple chunks and can be set quite large; the transfer protocol automatically adjusts its window size as a transfer progresses.
[in]	extend_window_divisor	Fractional position within a window at which a receive transfer extends its window size.

◆ Client() [2/2]

pw::transfer::Client::Client	(	rpc::Client &	rpc_client,
		uint32_t	channel_id,
		TransferThread &	transfer_thread
	)

inline

Deprecated:: Explicitly provide max_window_size_bytes instead.

Parameters

[in]	rpc_client	RPC client over which transfer streams are opened.
[in]	channel_id	RPC channel ID on which transfers are run.
[in]	transfer_thread	Thread used to process transfer events.

Member Function Documentation

◆ has_read_stream()

bool pw::transfer::Client::has_read_stream ( ) const

inline

Checks whether the client currently has an open RPC Read() stream.

Returns: true if a client read stream is open, false otherwise.

◆ has_write_stream()

bool pw::transfer::Client::has_write_stream ( ) const

inline

Checks whether the client currently has an open RPC Write() stream.

Returns: true if a client write stream is open, false otherwise.

◆ Read() [1/2]

Result< Handle > pw::transfer::Client::Read	(	uint32_t	resource_id,
		stream::Writer &	output,
		CompletionFunc &&	on_completion,
		chrono::SystemClock::duration	timeout = `cfg::kDefaultClientTimeout`,
		chrono::SystemClock::duration	initial_chunk_timeout = `cfg::kDefaultInitialChunkTimeout`,
		uint32_t	initial_offset = `0u`
	)

inline

Begins a new read transfer for the given resource_id using the client's configured default protocol version.

Data read from the server is written to output. Due to the asynchronous nature of transfer operations, this function only returns an error status synchronously if called with invalid arguments; transfer errors during execution are reported through on_completion on the transfer thread.

Parameters

[in]	resource_id	ID of the server resource to read.
[in,out]	output	Stream to which received data is written.
[in]	on_completion	Callback invoked from the transfer thread with the overall transfer status when the transfer finishes.
[in]	timeout	Maximum time to wait for a chunk before retrying.
[in]	initial_chunk_timeout	Maximum time to wait for the server's initial response chunk before retrying.
[in]	initial_offset	Starting byte offset within the server resource.

Returns

A Result containing a Handle to manage the active transfer on success or one of the following error codes on failure:

INVALID_ARGUMENT: on_completion is null, the client's default protocol version is ProtocolVersion::kUnknown, or initial_offset is non-zero with a protocol version older than ProtocolVersion::kVersionTwo.

◆ Read() [2/2]

Result< Handle > pw::transfer::Client::Read	(	uint32_t	resource_id,
		stream::Writer &	output,
		CompletionFunc &&	on_completion,
		ProtocolVersion	protocol_version,
		chrono::SystemClock::duration	timeout = `cfg::kDefaultClientTimeout`,
		chrono::SystemClock::duration	initial_chunk_timeout = `cfg::kDefaultInitialChunkTimeout`,
		uint32_t	initial_offset = `0u`
	)

Begins a new read transfer for the given resource_id using an explicit protocol_version.

Data read from the server is written to output. Due to the asynchronous nature of transfer operations, this function only returns an error status synchronously if called with invalid arguments; transfer errors during execution are reported through on_completion on the transfer thread.

When initial_offset is non-zero, output is used as-is without seeking; the caller must position output beforehand if needed.

Parameters

[in]	resource_id	ID of the server resource to read.
[in,out]	output	Stream to which received data is written.
[in]	on_completion	Callback invoked from the transfer thread with the overall transfer status when the transfer finishes.
[in]	protocol_version	Protocol version to request for this transfer.
[in]	timeout	Maximum time to wait for a chunk before retrying.
[in]	initial_chunk_timeout	Maximum time to wait for the server's initial response chunk before retrying.
[in]	initial_offset	Starting byte offset within the server resource.

Returns

A Result containing a Handle to manage the active transfer on success or one of the following error codes on failure:

INVALID_ARGUMENT: on_completion is null, protocol_version is ProtocolVersion::kUnknown, or initial_offset is non-zero with a protocol version older than ProtocolVersion::kVersionTwo.

◆ set_extend_window_divisor()

Status pw::transfer::Client::set_extend_window_divisor ( uint32_t extend_window_divisor )

inline

Sets the window divisor at which receive transfers extend their window.

Parameters

[in] extend_window_divisor Fractional divisor (must be greater than 1).

Returns

OK: The divisor was updated.
INVALID_ARGUMENT: extend_window_divisor is 1 or 0.

◆ set_max_lifetime_retries()

constexpr Status pw::transfer::Client::set_max_lifetime_retries ( uint32_t max_lifetime_retries )

inlineconstexpr

Sets the maximum total retries allowed over the lifetime of a transfer.

Parameters

[in] max_lifetime_retries Maximum lifetime retries (must be greater than or equal to max_retries).

Returns

OK: max_lifetime_retries was updated.
INVALID_ARGUMENT: max_lifetime_retries is less than max_retries.

◆ set_max_retries()

constexpr Status pw::transfer::Client::set_max_retries ( uint32_t max_retries )

inlineconstexpr

Sets the maximum number of retries for an individual chunk on new transfers.

Parameters

[in] max_retries Retry count (must be between 1 and the smaller of max_lifetime_retries and 255).

Returns

OK: max_retries was updated.
INVALID_ARGUMENT: max_retries is 0, exceeds max_lifetime_retries, or exceeds std::numeric_limits<uint8_t>::max().

◆ set_protocol_version()

constexpr void pw::transfer::Client::set_protocol_version ( ProtocolVersion new_version )

inlineconstexpr

Sets the default protocol version requested when starting new transfers.

Parameters

[in] new_version Protocol version to request by default.

◆ Write() [1/2]

Result< Handle > pw::transfer::Client::Write	(	uint32_t	resource_id,
		stream::Reader &	input,
		CompletionFunc &&	on_completion,
		chrono::SystemClock::duration	timeout = `cfg::kDefaultClientTimeout`,
		chrono::SystemClock::duration	initial_chunk_timeout = `cfg::kDefaultInitialChunkTimeout`,
		uint32_t	initial_offset = `0u`
	)

inline

Begins a new write transfer for the given resource_id using the client's configured default protocol version.

Data from input is sent to the server. Due to the asynchronous nature of transfer operations, this function only returns an error status synchronously if called with invalid arguments; transfer errors during execution are reported through on_completion on the transfer thread.

Parameters

[in]	resource_id	ID of the server resource to write.
[in,out]	input	Stream from which data to transmit is read.
[in]	on_completion	Callback invoked from the transfer thread with the overall transfer status when the transfer finishes.
[in]	timeout	Maximum time to wait for a chunk before retrying.
[in]	initial_chunk_timeout	Maximum time to wait for the server's initial response chunk before retrying.
[in]	initial_offset	Starting byte offset within the server resource.

Returns

A Result containing a Handle to manage the active transfer on success or one of the following error codes on failure:

INVALID_ARGUMENT: on_completion is null, the client's default protocol version is ProtocolVersion::kUnknown, or initial_offset is non-zero with a protocol version older than ProtocolVersion::kVersionTwo.

◆ Write() [2/2]

Result< Handle > pw::transfer::Client::Write	(	uint32_t	resource_id,
		stream::Reader &	input,
		CompletionFunc &&	on_completion,
		ProtocolVersion	protocol_version,
		chrono::SystemClock::duration	timeout = `cfg::kDefaultClientTimeout`,
		chrono::SystemClock::duration	initial_chunk_timeout = `cfg::kDefaultInitialChunkTimeout`,
		uint32_t	initial_offset = `0u`
	)

Begins a new write transfer for the given resource_id using an explicit protocol_version.

Data from input is sent to the server. Due to the asynchronous nature of transfer operations, this function only returns an error status synchronously if called with invalid arguments; transfer errors during execution are reported through on_completion on the transfer thread.

When initial_offset is non-zero, input is used as-is without seeking; the caller must position input beforehand if needed.

Parameters

[in]	resource_id	ID of the server resource to write.
[in,out]	input	Stream from which data to transmit is read.
[in]	on_completion	Callback invoked from the transfer thread with the overall transfer status when the transfer finishes.
[in]	protocol_version	Protocol version to request for this transfer.
[in]	timeout	Maximum time to wait for a chunk before retrying.
[in]	initial_chunk_timeout	Maximum time to wait for the server's initial response chunk before retrying.
[in]	initial_offset	Starting byte offset within the server resource.

Returns

A Result containing a Handle to manage the active transfer on success or one of the following error codes on failure:

INVALID_ARGUMENT: on_completion is null, protocol_version is ProtocolVersion::kUnknown, or initial_offset is non-zero with a protocol version older than ProtocolVersion::kVersionTwo.

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

pw_transfer/public/pw_transfer/client.h

Overview

Classes

Public Types

Public Member Functions

Friends

Member Typedef Documentation

◆ CompletionFunc

Constructor & Destructor Documentation

◆ Client() [1/2]

◆ Client() [2/2]

Member Function Documentation

◆ has_read_stream()

◆ has_write_stream()

◆ Read() [1/2]

◆ Read() [2/2]

◆ set_extend_window_divisor()

◆ set_max_lifetime_retries()

◆ set_max_retries()

◆ set_protocol_version()

◆ Write() [1/2]

◆ Write() [2/2]