// Copyright 2019 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.

library fuchsia.bluetooth.test;

using fuchsia.bluetooth as bt;

/// Error codes that can be generated for emulator-wide configurations.
enum EmulatorError {
    FAILED = 1;
    HCI_ALREADY_PUBLISHED = 2;
};

/// Error codes that are generated for functions that manipulate fake peers.
enum EmulatorPeerError {
    ADDRESS_REPEATED = 1;
    PARAMETERS_INVALID = 2;
    NOT_FOUND = 3;
};

// TODO(BT-229): Add state structures for other LE and BR/EDR operations.
// TODO(armansito): Add ability to publish GATT services
// TODO(armansito): Add ability to publish SDP records
// TODO(armansito): Add ability to specify Bluetooth HCI version.

/// Pre-set HCI configurations.
enum HciConfig {
    /// Support both BR/EDR and LE in LMP features.
    DUAL_MODE = 1;

    /// Limits supported features and HCI commands to those that are required for LE only.
    LE_ONLY = 2;
};

/// The HCI ACL data flow-control parameters.
struct AclBufferSettings {
    /// ACL frame MTU in bytes.
    uint16 data_packet_length;

    /// The maximum number of ACL frames that the controller can buffer.
    uint8 total_num_data_packets;
};

/// Controller settings used by the emulator.
table EmulatorSettings {
    /// The `BD_ADDR` (BR/EDR) or LE Public Device Address. Defaults to "00:00:00:00:00:00".
    1: bt.Address address;

    /// Supported HCI command configuration. Defaults to "`DUAL_MODE`".
    2: HciConfig hci_config;

    /// True if the 5.0 extended advertising features are supported. Defaults to "false".
    3: bool extended_advertising;

    /// The ACL-U data buffer settings. Defaults to
    ///    data_packet_length: 1024
    ///    total_num_data_packets: 5
    /// IF `hci_config` is set to `DUAL_MODE`. Defaults to null otherwise.
    4: AclBufferSettings acl_buffer_settings;

    /// The LE-U ACL data buffer settings. Defaults to
    ///    data_packet_length: 251
    ///    total_num_data_packets: 5
    5: AclBufferSettings le_acl_buffer_settings;
};

struct AdvertisingData {
    bytes:MAX_LEGACY_ADVERTISING_DATA_LENGTH data;
};

/// Parameters used to emulate a peer's behavior over the Low Energy transport.
table LowEnergyPeerParameters {
    /// The LE identity address of the peer. This field is mandatory.
    1: bt.Address address;

    /// When present and true, the peer will send connectable advertisements and accept connection
    /// requests. The peer will ignore connection requests if not connectable.
    2: bool connectable;

    /// The advertising data contents. If not present, the advertising data sent by this peer will
    /// be empty.
    3: AdvertisingData advertisement;

    /// The scan response data contents. When present, the fake controller will generate scannable
    /// advertising packets and scan response events.
    4: AdvertisingData scan_response;
};

/// Parameters used to emulate a peer's behavior over the BR/EDR transport.
table BredrPeerParameters {
    /// The BD_ADDR of the peer. This field is mandatory.
    1: bt.Address address;

    /// When present and true, the peer will accept connection requests. The peer will ignore
    /// connection requests if not connectable.
    2: bool connectable;

    /// The device class reported in the inquiry response for this peer during device discovery.
    3: bt.DeviceClass device_class;
};

enum ConnectionState {
    CONNECTED = 1;
    DISCONNECTED = 2;
};

/// Protocol used to drive the state of a fake peer device.
protocol Peer {
    /// Assign a HCI `status` for the controller to generate in response to connection requests.
    /// Applies to all successive HCI_Create_Connection and HCI_LE_Create_Connection commands. The
    /// procedure is acknowledged with an empty response.
    AssignConnectionStatus(HciError status) -> ();

    /// Emulates a LE connection event. Does nothing if the peer is already connected. The
    /// `role` parameter determines the link layer connection role.
    EmulateLeConnectionComplete(bt.ConnectionRole role);

    /// Emulate disconnection. Does nothing if the peer is not connected.
    EmulateDisconnectionComplete();

    /// Watch connection state changes using the
    /// [hanging get pattern](/docs/development/api/fidl.md#delay-responses-using-hanging-gets).
    /// Notifies the most recent controller connection state if there has been a change since the
    /// last time this method was called.
    ///
    /// Only one call to this method can be outstanding at a given time. The
    /// [`fuchsia.bluetooth.test/Peer`] channel will be closed if a call is received when one is
    /// already pending.
    WatchConnectionStates() -> (vector<ConnectionState> states);
};

/// Protocol used to emulate a Bluetooth controller that supports the standard Bluetooth HCI.
[Discoverable]
protocol HciEmulator {
    /// Publish a bt-hci device using the provided `settings`. Each HciEmulator instance can only
    /// manage a single bt-hci device. Returns Emulator.`HCI_ALREADY_PUBLISHED` if the device has
    /// already been published.
    Publish(EmulatorSettings settings) -> () error EmulatorError;

    /// Inserts a new LE peer device to be emulated by this controller. Once registered, the state
    /// of the fake peer can be driven and observed using the `peer` handle.
    ///
    /// A reply will be sent to acknowledge the creation of the fake peer. If a peer cannot be
    /// initialized (e.g. due to a missing required field in `parameters` or for containing an
    /// address that is already emulated) the `peer` handle will be closed and an error reply will
    /// be sent.
    ///
    /// The peer will appear in advertising reports and respond to requests according to its
    /// configuration as long as the `peer` channel is open. The emulator stops emulating this peer
    /// when the channel gets closed, which makes it no longer discoverable and not respond to any
    /// requests.
    AddLowEnergyPeer(LowEnergyPeerParameters parameters, request<Peer> peer) -> () error EmulatorPeerError;

    /// Inserts a new BR/EDR peer device to be emulated by this controller. Once registered, the state
    /// of the fake peer can be driven and observed using the `peer` handle.
    ///
    /// A reply will be sent to acknowledge the creation of the fake peer. If a peer cannot be
    /// initialized (e.g. due to a missing required field in `parameters` or for containing an
    /// address that is already emulated) the `peer` handle will be closed and an error reply will
    /// be sent.
    ///
    /// The peer will appear in inquiry results and respond to requests according to its
    /// configuration as long as the `peer` channel is open. The emulator stops emulating this peer
    /// when the channel gets closed, which makes it no longer discoverable and not respond to any
    /// requests.
    AddBredrPeer(BredrPeerParameters parameters, request<Peer> peer) -> () error EmulatorPeerError;

    /// Returns the most recent set of state transitions for the link layer LE scan procedure. This
    /// method returns when there has been a state change since the last invocation of this method
    /// by this client.
    ///
    /// Only one call to this method can be outstanding at a given time. The
    /// [`fuchsia.bluetooth.test/HciEmulator`] channel will be closed if a call received when one is
    /// already pending.
    /// (see [hanging get pattern](//docs/development/api/fidl.md#delay-responses-using-hanging-gets))
    WatchLeScanStates() -> (vector<LeScanState> states);

    /// Returns the most recent set of state transitions for the link layer LE legacy advertising
    /// procedure. This method returns when there has been a state change since the last invocation
    /// of this method by this client.
    ///
    /// Only one call to this method can be outstanding at a given time. The
    /// [`fuchsia.bluetooth.test/HciEmulator`] channel will be closed if a call received when one is
    /// already pending.
    /// (see [hanging get pattern](//docs/development/api/fidl.md#delay-responses-using-hanging-gets))
    WatchLegacyAdvertisingStates() -> (vector<LegacyAdvertisingState> states);
};