// PureLife Device Provisioning Protocol, version 1.0 (Draft).
//
// Endpoint `pld-ctrl`: Commit of the pending configuration and Finish of
// the provisioning. See the Device Provisioning Protocol (pld-provisioning.html), section 9.3.

syntax = "proto3";

package pld;

import "pld_constants.proto";

// Type of the message carried in `CtrlPayload`.
enum CtrlMsgType {
  // Not set. A payload with this type is invalid.
  CTRL_MSG_TYPE_UNSPECIFIED = 0;

  // Provisioner to Device: `CommitCommand`.
  CTRL_MSG_TYPE_COMMIT_COMMAND = 1;

  // Device to Provisioner: `CommitResponse`.
  CTRL_MSG_TYPE_COMMIT_RESPONSE = 2;

  // Provisioner to Device: `FinishCommand`.
  CTRL_MSG_TYPE_FINISH_COMMAND = 3;

  // Device to Provisioner: `FinishResponse`.
  CTRL_MSG_TYPE_FINISH_RESPONSE = 4;
}

// Persists the pending configuration atomically.
//
// Requires a complete pending configuration. Allowed regardless of the
// Wi-Fi state and of the result of the Server check. After the first
// successful Commit the Device counts as provisioned. Has no fields.
message CommitCommand {}

// Result of `CommitCommand`.
message CommitResponse {
  // Required. Result of the command. `STATUS_INVALID_ARGUMENT` if the
  // pending configuration is incomplete.
  Status status = 1;

  // Optional. Human readable detail for logs and support, English, at most
  // 64 bytes. Names the missing field on `STATUS_INVALID_ARGUMENT`.
  string detail = 2;
}

// Ends the provisioning.
//
// Requires a Commit in this Provisioning period. The Device sends the
// response, stops the provisioning service and enters Operating. Has no
// fields.
message FinishCommand {}

// Result of `FinishCommand`.
message FinishResponse {
  // Required. Result of the command. `STATUS_INVALID_STATE` if no Commit
  // has happened.
  Status status = 1;

  // Optional. Human readable detail for logs and support, English, at most
  // 64 bytes. MUST be empty when `status` is `STATUS_OK`.
  string detail = 2;
}

// Payload of the `pld-ctrl` endpoint.
message CtrlPayload {
  // Required. Identifies which member of `payload` is set.
  CtrlMsgType msg = 1;

  // The command or response. Exactly one member is set.
  oneof payload {
    // Set when `msg` is `CTRL_MSG_TYPE_COMMIT_COMMAND`.
    CommitCommand commit_command = 10;

    // Set when `msg` is `CTRL_MSG_TYPE_COMMIT_RESPONSE`.
    CommitResponse commit_response = 11;

    // Set when `msg` is `CTRL_MSG_TYPE_FINISH_COMMAND`.
    FinishCommand finish_command = 12;

    // Set when `msg` is `CTRL_MSG_TYPE_FINISH_RESPONSE`.
    FinishResponse finish_response = 13;
  }
}