// # URL Payloads
//
// These payloads are part of universal URLs (e.g. group invite links). After
// serializing the protobuf messages, they are encoded in URL safe Base64
// (according to RFC 3548).
//
// Note: Be aware that there is no canonical representation of a URL if it
// contains a protobuf message.

syntax = "proto3";

package url;

option java_package = "ch.threema.protobuf.url";
option java_multiple_files = true;
option php_namespace = "Threema\\Protocols\\Url";

import "common.proto";
import "md-d2d-rendezvous.proto";

// Offer or request to join the (multi-)device group.
//
// When generated by an existing or a new device, the URL is formed using the
// `threema` scheme in the following way:
//
// ```text
// threema://device-group/join#<url-safe-base64(DeviceGroupJoinRequestOrOffer)>
// ```
//
// When receiving this message:
//
// 1. If `version` or `variant` is not supported, abort these steps.
// 2. Follow the description of `RendezvousInit` to continue.
message DeviceGroupJoinRequestOrOffer {
  // Device join protocol version used by the device.
  enum Version {
    // Initial version.
    V1_0 = 0;
  }
  Version version = 1;

  // D2D protocol version (`d2d.ProtocolVersion`) used by the device
  //
  // If `0`, assume V0.1 (`0x0001`).
  uint32 d2d_protocol_version = 4;

  // Variant (_offer_ or _request_)
  message Variant {
    oneof type {
      // A device intends to join the (multi-)device group. `data` is to be
      // handled according to the _Device Join Protocol_ with `ND` being the
      // initiator.
      common.Unit request_to_join = 1;

      // A device intends to let another device join the (multi-)device group.
      // `data` is to be handled according to the _Device Join Protocol_ with
      // `ED` being the initiator.
      common.Unit offer_to_join = 2;
    }
  }
  Variant variant = 2;

  // Data necessary to initialise a 1:1 connection between two devices.
  d2d_rendezvous.RendezvousInit rendezvous_init = 3;
}
