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 aborting the transfer due to an error or user
  // cancellation. 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. When Error is received, no more messages relating to the transfer
  // should be sent, but the end sending the error should be prepared to handle
  // any messages that may already be on the wire.
  // Next Id: 6
  message Error {
    enum Type {
      UNSPECIFIED = 0;
      CANCELED = 1;
      UNEXPECTED_ERROR = 2;
      PROTOCOL_ERROR = 3;
      PERMISSION_DENIED = 4;
      OUT_OF_DISK_SPACE = 5;
      IO_ERROR = 6;
      NOT_LOGGED_IN = 7;
    }

    // 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;
    Error error = 5;
  }
}