syntax = "proto2";

option optimize_for = LITE_RUNTIME;

package remoting.protocol;

// Composite message type for messages sent over file-transfer data channels.
// Next Id: 7
message FileTransfer {
  // Sender->receiver message containing file metadata. Always sent before any
  // Data messages.
  // Next Id: 3
  message Metadata {
    optional string filename = 1;
    // Note: there may be edge cases in which the file is transmitted
    // successfully but doesn't exactly match the number of bytes reported here.
    // Thus, the implementation should wait for the End message to determine
    // when the file is complete and not rely on the exact size.
    optional uint64 size = 2;
  }

  // Sender->receiver message containing a chunk of file data.
  // Next Id: 2
  message Data { optional bytes data = 1; }

  // Sender->receiver message sent after the last data chunk, signaling that
  // the transfer is complete.
  // Next Id: 1
  message End {}

  // Receiver->sender message sent in response to the End message, indicating
  // that the file has been successfully saved.
  // Next Id: 1
  message Success {}

  // Bidirectional message canceling the transfer as the result of a user action
  // or otherwise not due to an error. When Cancel is received, no more messages
  // relating to the transfer should be sent, but the canceling end should be
  // prepared to handle any messages that may already be on the wire.
  // Next Id: 1
  message Cancel {}

  // Bidirectional message aborting the transfer due to an error. This may be
  // sent by the sender to signal a read error, by the receiver to signal a
  // write error, or by either side to signal any of the myriad of other things
  // that can go wrong while attempting to transfer a file.
  // Next Id: 6
  message Error {
    enum Type {
      UNSPECIFIED = 0;
      UNEXPECTED_ERROR = 1;
      PROTOCOL_ERROR = 2;
      PERMISSION_DENIED = 3;
      OUT_OF_DISK_SPACE = 4;
      IO_ERROR = 5;
    }

    // An error category to be used to select a user-displayed error message.
    optional Type type = 1;
    // The error code returned by the failed API call (if applicable).
    optional int32 api_error_code = 2;
    // The function in which the error occured.
    optional string function = 3;
    // The source file in which the error occured.
    optional string source_file = 4;
    // The line number on which the error occurred.
    optional uint32 line_number = 5;
  }

  oneof message {
    Metadata metadata = 1;
    Data data = 2;
    End end = 3;
    Success success = 4;
    Cancel cancel = 5;
    Error error = 6;
  }
}