diff options
Diffstat (limited to 'pw_transfer/transfer.proto')
| -rw-r--r-- | pw_transfer/transfer.proto | 59 |
1 files changed, 52 insertions, 7 deletions
diff --git a/pw_transfer/transfer.proto b/pw_transfer/transfer.proto index 6f598a071..839eb2cd2 100644 --- a/pw_transfer/transfer.proto +++ b/pw_transfer/transfer.proto @@ -1,4 +1,4 @@ -// Copyright 2021 The Pigweed Authors +// Copyright 2022 The Pigweed Authors // // Licensed under the Apache License, Version 2.0 (the "License"); you may not // use this file except in compliance with the License. You may obtain a copy of @@ -16,6 +16,9 @@ syntax = "proto3"; package pw.transfer; +option java_multiple_files = true; +option java_package = "dev.pigweed.pw_transfer"; + // The transfer RPC service is used to send data between the client and server. service Transfer { // Transfer data from the server to the client; a "download" from the client's @@ -38,6 +41,8 @@ message Chunk { // stable depending on the implementation. Sent in every request to identify // the transfer target. // + // LEGACY FIELD ONLY. Split into resource_id and session_id in transfer v2. + // // Read → ID of transfer // Read ← ID of transfer // Write → ID of transfer @@ -112,10 +117,10 @@ message Chunk { // OK: Transfer completed successfully. // DATA_LOSS: Transfer data could not be read/written (e.g. corruption). // INVALID_ARGUMENT: Received malformed chunk. - // NOT_FOUND: The requested transfer ID is not registered (read/write). + // NOT_FOUND: The requested resource ID is not registered (read/write). // OUT_OF_RANGE: The requested offset is larger than the data (read/write). // RESOURCE_EXHAUSTED: Concurrent transfer limit reached. - // UNIMPLEMENTED: Transfer ID does not support requested operation (e.g. + // UNIMPLEMENTED: Resource ID does not support requested operation (e.g. // trying to write to a read-only transfer). // // Read → Transfer complete. @@ -138,10 +143,10 @@ message Chunk { enum Type { // Chunk containing transfer data. - TRANSFER_DATA = 0; + DATA = 0; // First chunk of a transfer (only sent by the client). - TRANSFER_START = 1; + START = 1; // Transfer parameters indicating that the transmitter should retransmit // from the specified offset. @@ -153,11 +158,21 @@ message Chunk { PARAMETERS_CONTINUE = 3; // Sender of the chunk is terminating the transfer. - TRANSFER_COMPLETION = 4; + COMPLETION = 4; // Acknowledge the completion of a transfer. Currently unused. // TODO(konkers): Implement this behavior. - TRANSFER_COMPLETION_ACK = 5; + COMPLETION_ACK = 5; + + // Acknowledges a transfer start request, assigning a session ID for the + // transfer and optionally negotiating the protocol version. Sent from + // server to client. + START_ACK = 6; + + // Confirmation of a START_ACK's assigned session ID and negotiated + // parameters, sent by the client to the server. Initiates the data transfer + // proper. + START_ACK_CONFIRMATION = 7; }; // The type of this chunk. This field should only be processed when present. @@ -169,4 +184,34 @@ message Chunk { // Write → Chunk type (data). // Write ← Chunk type (start/parameters). optional Type type = 10; + + // Unique identifier for the source or destination of transfer data. May be + // stable or ephemeral depending on the implementation. Only sent during the + // initial handshake phase of a version 2 or higher transfer. + // + // Read → ID of transferable resource + // Read ← ID of transferable resource + // Write → ID of transferable resource + // Write ← ID of transferable resource + optional uint32 resource_id = 11; + + // Unique identifier for a specific transfer session. Assigned by a transfer + // service during the initial handshake phase, and persists for the remainder + // of that transfer operation. + // + // Read → ID of transfer session + // Read ← ID of transfer session + // Write → ID of transfer session + // Write ← ID of transfer session + optional uint32 session_id = 12; + + // The protocol version to use for this transfer. Only sent during the initial + // handshake phase of a version 2 or higher transfer to negotiate a common + // protocol version between the client and server. + // + // Read → Desired (START) or configured (START_ACK_CONFIRMATION) version. + // Read ← Configured protocol version (START_ACK). + // Write → Desired (START) or configured (START_ACK_CONFIRMATION) version. + // Write ← Configured protocol version (START_ACK). + optional uint32 protocol_version = 13; } |