// Copyright (C) 2020 The Android Open Source Project
//
// 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 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.

// Note that if you add/remove methods in this file you must update
// the metrics sql as well ./android/scripts/gen-grpc-sql.py
//
// Please group deleted methods in a block including the date (MM/DD/YY)
// it was removed. This enables us to easily keep metrics around after removal
//
// List of deleted methods
// rpc iWasDeleted (03/12/12)
// ...
syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.android.emulator.control";
option objc_class_prefix = "AEC";

package android.emulation.control;
import "google/protobuf/empty.proto";

// The ADB service enables you to interact with the running Adb service inside
// the emulator. This service is usually not available as it has the ability to
// retrieve the private adb key from the running image and make adb accessible
// if and only if:
//
// 1. The private key is available to the running emulator.
// 2. The public key corresponding the private key is embedded in the encrypted
//    partition.
//
// This service is usually *ONLY* available to containerized emulators that are
// running with mutual authentication on the gRPC endpoint (that is SSL is
// enabled and a valid client certificate is required.).
service Adb {
    // Pulls the private key that the emulator uses to communicate with the
    // emulator. This private key should be made accessible to adb when you wish
    // to establish a connection to this emulator.
    //
    // The following gRPC error codes can be returned:
    // -  unimplemented (code 14) if the AdbService is not available.
    // -  aborted (code 10) if:
    //     - The private key file cannot be found.
    //     - The private key file cannot be read.
    rpc pullAdbKey(google.protobuf.Empty) returns(AdbKey);


    // Forwards the incoming bytes to the running adb deamon.
    // This RPC is not implemented and will return an unimplemented error.
    rpc forwardAdb(AdbPacket) returns(AdbPacket);
}

message AdbKey {
    // The private key used to derive the public key that is embedded in the
    // emulator. This private key must be made available to ADB in order to
    // establish a connection to the emulator *without* requiring interaction.
    //
    // The private key must be made available to adb. This can be done
    // by:
    //
    // - Saving it as a file and adding it to the $ADB_VENDOR_KEYS enviroment
    // variable and restarting adb.
    //
    // or
    //
    // - Saving it the existing $ADB_VENDOR_KEYS search path used by adb.
    string private_key = 1;
};

message AdbPacket {
    // Payload that needs to be forwarded.
    bytes payload = 1;

    // status fields.
    bool success = 2;
    string err = 3;
};