// Copyright (c) 2018 Anki, Inc.
//
// 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 the License in the file LICENSE.txt or at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Behavior related messages

syntax = "proto3";

package Anki.Vector.external_interface;

import "messages.proto";

// Tell the behavior stream to release control from the SDK.
// The stream may stay alive, but Vector will be allowed to run
// his normal behaviors.
message ControlRelease {}

// Request control of the behavior system at a given priority.
// Currently there is only one priority level.
message ControlRequest {
  // Where in the behavior tree the SDK code should be executed.
  enum Priority {
    // Unknown priority. Used for versions that don't understand old priority levels.
    UNKNOWN = 0;
    // Highest priority level. Suppresses most automatic physical reactions, use with caution. 
    OVERRIDE_BEHAVIORS = 10;
    // Normal priority level. Directly under mandatory physical reactions.
    DEFAULT = 20;
    // Enable long-running SDK control between script execution.  Not to be used for regular behavior control.
    RESERVE_CONTROL = 30;
  }
  // Where in the behavior tree the SDK code should be executed.
  Priority priority = 1;
}

// Messages that can be sent to the behavior stream. Explicitly
// requesting or releasing control.
message BehaviorControlRequest {
  oneof request_type {
    // Release control of the behavior system back to Vector.
    ControlRelease control_release = 1;
    // Request control of the behavior system for the SDK.
    ControlRequest control_request = 2;
  }
}

// The SDK user is now free to run any actions and behaviors they like.
// Until a ControlLostResponse is received, they are directly in control
// of Vector's behavior system.
message ControlGrantedResponse {}

// This informs the user that they lost control of the behavior system.
// All direct actions will be unavailable via the sdk until control is regained.
// Regaining control can be either through a call to ControlRequest, or
// can be as a result of conditions passed to the original ControlRequest.
message ControlLostResponse {}

// The ability to reserve control before/after SDK scripts has been lost.  
// This control can be regained through another ControlRequest.
message ReservedControlLostResponse {}

// Responses from the behavior stream.
message BehaviorControlResponse {
  oneof response_type {
    // The SDK user is now free to directly control Vector.
    ControlGrantedResponse control_granted_response = 1;
    // Control of the behavior system has been lost to a higher priority behavior.
    ControlLostResponse control_lost_event = 2;
    // Used by Vector to verify the connection is still alive.
    KeepAlivePing keep_alive = 3;
    // Behavior system lock has been lost to another connection
    ReservedControlLostResponse reserved_control_lost_event = 4;
  }
}