// Copyright 2023 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=HEAD)
library fuchsia.bluetooth.pandora;

type ServiceError = flexible enum {
    /// The requested component was already running.
    ALREADY_RUNNING = 1;

    /// The provided IP address could not be parsed.
    INVALID_IP = 2;

    /// A connection could not be established to the provided address.
    CONNECTION_FAILED = 3;

    /// The request failed internally.
    FAILED = 4;
};

/// Controls the lifecycle of a gRPC server that implements the [Pandora Bluetooth testing
/// interfaces](https://github.com/google/bt-test-interfaces).
@discoverable
open protocol GrpcServerController {
    /// Start Pandora interface gRPC server.
    ///
    /// + request `port` is the Fuchsia port on which the gRPC server will listen.
    ///
    /// * error Returns `ALREADY_RUNNING` if a gRPC server is already running.
    /// * error Returns `FAILED` if there was an internal error starting the server.
    flexible Start(table {
        1: port uint16;
    }) -> () error ServiceError;

    /// Stop gRPC server if running.
    flexible Stop() -> ();
};

/// Controls instances of bt-rootcanal, a tool that proxies HCI traffic between Fuchsia Bluetooth
/// and a [Rootcanal](https://github.com/google/rootcanal) server.
@discoverable
open protocol RootcanalClientController {
    /// Start bt-rootcanal if it is not already running.
    ///
    /// + request `ip` is the IP address of the host running the Rootcanal server.
    /// + request `port` is the port on the host on which the Rootcanal server is listening.
    ///
    /// * error Returns `ALREADY_RUNNING` if bt-rootcanal is already running.
    /// * error Returns `INVALID_IP` if the IP address could not be parsed.
    /// * error Returns `CONNECTION_FAILED` if a connection to the Rootcanal server could not be
    ///         established.
    /// * error Returns `FAILED` if there was an internal error starting bt-rootcanal.
    flexible Start(table {
        1: ip string:32;
        2: port uint16;
    }) -> () error ServiceError;

    /// Stop bt-rootcanal if running.
    flexible Stop() -> ();
};