Lines Matching full:transfer
6 ``pw_transfer`` is a reliable data transfer protocol which runs on top of
20 Transfer thread
23 required. The transfer thread is used to process all transfer-related events
24 safely. The same transfer thread can be shared by a transfer client and service
29 All user-defined transfer callbacks (i.e. the virtual interface of a
30 ``Handler`` or completion function in a transfer client) will be
31 invoked from the transfer thread's context.
33 In order to operate, a transfer thread requires two buffers:
35 - The first is a *chunk buffer*. This is used to stage transfer packets received
36 by the RPC system to be processed by the transfer thread. It must be large
39 - The second is an *encode buffer*. This is used by the transfer thread to
44 A transfer thread is created by instantiating a ``pw::transfer::Thread``. This
68 // The maximum amount of data that should be sent within a single transfer
79 pw::transfer::Thread<kMaxConcurrentClientTransfers,
85 // pw::transfer::TransferThread is the generic, non-templated version of the
87 pw::transfer::TransferThread& GetSystemTransferThread() {
91 .. _pw_transfer-transfer-server:
93 Transfer server
99 is defined (``pw_transfer/public/pw_transfer/handler.h``). Transfer handlers
101 initialization and completion code. Custom transfer handler implementations
106 A transfer handler should be implemented and instantiated for each unique
110 Handlers are registered with the transfer service. This may be done during
112 support ephemeral transfer resources. A boolean is returned with registration/
115 **Example transfer handler implementation**
120 #include "pw_transfer/transfer.h"
122 // A simple transfer handler which reads data from an in-memory buffer.
123 class SimpleBufferReadHandler : public pw::transfer::ReadOnlyHandler {
136 above transfer can choose how to fill and interpret this information. The status
156 The transfer service is instantiated with a reference to the system's transfer
159 **Example transfer service initialization**
163 #include "pw_transfer/transfer.h"
167 // In a write transfer, the maximum number of bytes to receive at one time
169 // transfer handler's stream::Writer. Should be set reasonably high; the
170 // transfer will attempt to determine an optimal window size based on the
174 pw::transfer::TransferService transfer_service(
178 // be used by the transfer client and server to identify the handler.
187 // Register the handler with the transfer service, then the transfer service
193 Transfer client
195 ``pw_transfer`` provides a transfer client capable of running transfers through
200 Currently, a transfer client is only capable of running transfers on a single
203 The transfer client provides the following APIs for managing data transfers:
205 …w::Transfer::Client::Handle> pw::transfer::Client::Read(uint32_t resource_id, pw::stream::Writer& …
207 Reads data from a transfer server to the specified ``pw::stream::Writer``.
209 transfer.
211 Due to the asynchronous nature of transfer operations, this function will only
217 …w::Transfer::Client::Handle> pw::transfer::Client::Write(uint32_t resource_id, pw::stream::Reader&…
219 Writes data from a source ``pw::stream::Reader`` to a transfer server.
221 transfer.
223 Due to the asynchronous nature of transfer operations, this function will only
229 Transfer handles
231 Each transfer session initiated by a client returns a ``Handle`` object which
232 is used to manage the transfer. These handles support the following operations:
234 .. cpp:function:: pw::Transfer::Client::Handle::Cancel()
236 Terminates the ongoing transfer.
238 .. cpp:function:: pw::Transfer::Client::Handle::SetTransferSize(size_t size_bytes)
240 In a write transfer, indicates the total size of the transfer resource.
253 // In a read transfer, the maximum number of bytes to receive at one time
255 // transfer's stream. Should be set reasonably high; the transfer will
259 pw::transfer::Client transfer_client(GetSystemRpcClient(),
274 Result<pw::transfer::Client::Handle> handle = transfer_client.Read(
285 // Block until the transfer completes.
292 Transfer data is sent and received through the ``pw::Stream`` interface, which
294 fixed-size may optionally indicate this to the transfer client and server,
295 which will be shared with the transfer peer to enable features such as progress
298 The transfer size can only be set on the transmitting side of the transfer;
299 that is, the client in a ``Write`` transfer or the server in a ``Read``
300 transfer.
307 **Setting a transfer size from a transmitting client**
311 Result<pw::transfer::Client::Handle> handle = client.Write(...);
316 **Setting a transfer size on a server resource**
319 function to return the size of its transfer resource.
323 class MyResourceHandler : public pw::transfer::ReadOnlyHandler {
333 Atomic File Transfer Handler
337 with atomic semantics. It guarantees that the target file of the transfer is
339 target file. If any transfer failure occurs, the transfer is aborted and the
353 The default maximum number of times a transfer client should retry sending a
354 chunk when no response is received. Can later be configured per-transfer when
359 The default maximum number of times a transfer server should retry sending a
367 The default maximum number of times a transfer should retry sending any chunk
377 in a transfer client before retrying. This can later be configured
378 per-transfer.
383 on the server before retrying. This can later be configured per-transfer.
388 response to a transfer before retrying. This can later be configured
389 per-transfer.
397 The fractional position within a window at which a receive transfer should
422 Configurable log level for the entire transfer module.
437 Maximum time to wait for a transfer event to be processed before dropping
439 to process transfer data, this can be used to prevent threads from blocking
449 be handled by the user through the transfer handler interfaces of `GetStatus`
453 having the transfer client calling `read()` or `write()` with an offset
461 On the server side, the offset is accepted, and passed to the transfer
463 specifically by the handler in order to support the offset transfer. The
464 transfer handler confirms that the start offset is valid for the read/write
466 transfer operation. Older server sw will ignore the offset, so the clients
475 See the :ref:`transfer handler <pw_transfer-transfer-server>` documentation for
478 ``pw/transfer/public/pw_transfer/handler.h``
495 transfer_service = rpcs.pw.transfer.Transfer
499 # Read the transfer resource with ID 3 from the server.
505 # Send some data to the server. The transfer manager does not have to be
523 service = client.channel()!.service('pw.transfer.Transfer')!;
542 pw_transfer provides a Java client. The transfer client returns a
544 to represent the results of a read or write transfer.
553 // Create a new transfer client.
562 // Start a read transfer.
565 // Start a write transfer.
568 // Get the data from the read transfer.
571 // Wait for the write transfer to complete.
594 defined by the implementers of the server-side transfer node.
596 The series of chunks exchanged in an individual transfer operation for a
597 resource constitute a transfer *session*. The session runs from its opening
598 chunk until either a terminating chunk is received or the transfer times out.
605 ``pw_transfer`` attempts to be a reliable data transfer protocol.
613 A transfer can only be reliable if its underlying data stream is seekable.
614 A non-seekable stream could prematurely terminate a transfer following a
627 A read or write transfer for a resource is initiated by a transfer client. The
629 in a ``START`` chunk, indicating that it wishes to begin a new transfer. This
633 Upon receiving a ``START`` chunk, the transfer server checks whether the
638 session, and configured protocol version for the transfer.
644 Throughout a transfer, the receiver maintains a window of how much data it can
647 of the transfer.
656 transfer detects a packet loss or times out. Once this occurs, the window size
657 is halved and the transfer enters a "congestion avoidance" phase for the
661 Transfer completion
663 Either side of a transfer can terminate the operation at any time by sending a
664 ``COMPLETION`` chunk containing the final status of the transfer. When a
665 ``COMPLETION`` chunk is sent, the terminator of the transfer performs local
668 Upon receving a ``COMPLETION`` chunk, the transfer peer cancels any pending
679 Server to client transfer (read)
683 Client to server transfer (write)
689 .. literalinclude:: transfer.proto
699 sender or the receiver (see `Transfer roles`_).
710 | ``ABORTED`` | The service aborted the transfer because the |
712 | | transfer handler, but not sent to the client |
713 | | because it restarted the transfer. |
715 | ``CANCELLED`` | The client cancelled the transfer. |
722 | ``FAILED_PRECONDITION`` | Received chunk for transfer that is not active. |
730 | ``PERMISSION_DENIED`` | The transfer does not support the requested |
740 | | cannot begin a new transfer at this time. |
750 Transfer roles
752 Every transfer has two participants: the sender and the receiver. The sender
754 transferred and sends the final status when the transfer is complete.
764 start([Client initiates<br>transfer]) -->data_request
765 data_request[Receive transfer<br>parameters]-->send_chunk
780 done([Transfer complete])
787 start([Client initiates<br>transfer]) -->request_bytes
788 request_bytes[Set transfer<br>parameters]-->wait
808 done([Transfer complete])
813 reliability improvements of its modern protocol. As a result of this, transfer
820 - There is no distinction between a transfer resource and session --- a single
821 ``transfer_id`` field represents both. Only one transfer for a given resource
822 can run at a time, and it is not possible to determine where one transfer for
825 a transfer ID and starting transfer parameters (during a read), and the data
826 transfer phase begins immediately.
828 completes a transfer by sending a status chunk, it does not wait for the peer
829 to acknowledge. Resources used by the transfer are immediately freed, and
832 Transfer clients request the latest transfer protocol version by default, but
833 may be configured to request the legacy protocol. Transfer server and client
834 implementations detect if their transfer peer is running the legacy protocol and