// Copyright 2018 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.host;

using fuchsia.bluetooth;
using fuchsia.bluetooth.control;
using fuchsia.bluetooth.gatt;
using fuchsia.bluetooth.le;
using fuchsia.bluetooth.bredr;

// TODO(BT-814): Convert all comments below to doc-comments.

/// Represents persistent local host data.
// TODO(BT-813): Consider using a table instead of struct.
struct HostData {
    /// The local Identity Resolving Key used by a bt-host device to generate Resolvable Private
    /// Addresses when privacy is enabled.
    ///
    /// NOTE: This key is distributed to LE peers during pairing procedures. The client must take
    /// care to assign an IRK that consistent with the local bt-host identity.
    // TODO(BT-815): Document behavior once there is a better privacy policy when |irk| is null.
    LocalKey? irk;
};

// Interface for interacting with a Bluetooth host device (bt-host)
protocol Host {
    // The following methods fulfill a given interface request. bt-host device
    // will start processing FIDL messages. If the request cannot be fulfilled,
    // the bt-host device will close its end of the given channel.
    RequestLowEnergyCentral(request<fuchsia.bluetooth.le.Central> central);
    RequestLowEnergyPeripheral(request<fuchsia.bluetooth.le.Peripheral> peripheral);
    RequestGattServer(request<fuchsia.bluetooth.gatt.Server> server);
    RequestProfile(request<fuchsia.bluetooth.bredr.Profile> profile);

    // Shuts down the host, ending all active Bluetooth procedures:
    //
    // * All FIDL interface handles associated with this host are closed and all
    //   connections initiated via FIDL clients are severed.
    // * All scan, discovery, and advertising procedures are stopped.
    // * Bonded devices are cleared and removed from the auto-connect lists.
    // * Auto-connected peripherals are disconnected.
    //
    // This effectively resets the host to its initial state and the host remains
    // available for future requests.
    //
    // The Host will continue to send OnDeviceUpdated events as procedures get
    // terminated.
    Close();

    // Returns information about the Bluetooth adapter managed by this host.
    GetInfo() -> (fuchsia.bluetooth.control.AdapterInfo info);

    /// Assigns local data to this host.
    SetLocalData(HostData host_data);

    // Returns a list of all known connectable devices, included those that are
    // currently connected and/or bonded. This list does not include
    // non-connectable devices such as LE broadcasters.
    //
    // Notes:
    //
    // - When used in the GAP central role (BR/EDR or LE) the listed devices are
    // obtained during discovery and connection procedures. While in the
    // peripheral role, this will contain devices that have successfully initiated
    // connections to this host.
    //
    // - This list contains connectable devices that are discovered or connected
    // via other interfaces obtained using the interface request methods declared
    // above.
    ListDevices() -> (vector<fuchsia.bluetooth.control.RemoteDevice> devices);

    // Sets the local name for this adapter.
    SetLocalName(string local_name) -> (fuchsia.bluetooth.Status status);

    // Sets the device class for this adapter.
    SetDeviceClass(fuchsia.bluetooth.control.DeviceClass device_class)
        -> (fuchsia.bluetooth.Status status);

    // Initiates a general discovery procedure for BR/EDR and LE devices. On success, discovered
    // devices will be reported via AdapterDelegate.OnDeviceDiscovered().
    //
    // On the LE transport, only general-discoverable and connectable peripherals will be reported.
    //
    // Discovery will continue until it is terminated via StopDiscovery() or if the proxy to the
    // Adapter gets disconnected. If the device does not support BR/EDR, only LE
    // discovery will be performed.
    //
    // An OnDeviceUpdated event will be sent when the discovery procedures are
    // started.
    StartDiscovery() -> (fuchsia.bluetooth.Status status);

    // Terminates discovery if one was started via StartDiscovery(). The AdapterDelegate will stop
    // receiving device discovery notifications.
    //
    // NOTE: If another client is performing discovery (e.g. via its own le.Central interface handle),
    // then the system will continue performing device discovery even if this method results in
    // success.
    StopDiscovery() -> (fuchsia.bluetooth.Status status);

    // Sets whether this host should be connectable.
    SetConnectable(bool enabled) -> (fuchsia.bluetooth.Status status);

    // Sets whether this host should be discoverable.
    SetDiscoverable(bool enabled) -> (fuchsia.bluetooth.Status status);

    // Establish a BR/EDR and/or LE connection to the remote device with identifier |device_id|:
    //
    //   - If the device is known to support the BR/EDR transport then a logical link over that
    //     transport will be established to the device. If the connection attempt is successful,
    //     local services registered using "RequestProfile()" will be available to the peer.
    //     Traditional services discovered on the peer will be notified to local services
    //     asynchronously.
    //
    //   - If the device is known to support the LE transport then a logical link over that
    //     transport will be established to the device. If the connection attempt is successful,
    //     GATT services in the local database (populated via RequestGattServer()) will become
    //     available to the peer. Similarly, remote GATT services that are discovered on the
    //     peer will become available to holders of a gatt.Client capability and to device drivers
    //     that can bind to the bt-gatt-svc class of devices.
    //
    // The result of the procedure will be communicated via |status|. If the remote device
    // supports both BR/EDR and LE transports and a link cannot be established over both, then an
    // error Status will be returned and neither transport will be connected.
    Connect(string device_id) -> (fuchsia.bluetooth.Status status);

    /// Deletes a peer from the Bluetooth host. If the peer is connected, it
    /// will be disconnected, then OnDeviceUpdated will be sent. No
    /// OnBondRemoved will be sent. |device_id| will no longer to refer to any
    /// peer, even if the same device is discovered again.
    ///
    /// Returns a success only if the peer was found and it contained bond data
    /// that was deleted.
    ///
    /// TODO(BT-824): Delete peer immediately, not eventually.
    /// TODO(BT-562): Respond when disconnection completes, not immediately.
    Forget(string device_id) -> (fuchsia.bluetooth.Status status);

    // Enable or disable a passive LE background scan. When enabled, the bt-host
    // device will continuously perform a passive LE scan in the background when
    // no device discovery sessions are active and accept connection requests from
    // bonded peripherals.
    EnableBackgroundScan(bool enabled);

    /// Enable or disable the LE privacy feature. When enabled, the bt-host device will use a private
    /// device address in all LE procedures. When disabled, the public identity address will be used
    /// instead (which is the default).
    EnablePrivacy(bool enabled);

    // Assigns the pairing delegate that will respond to authentication challenges using the given
    // I/O capabilities. Setting a pairing delegate cancels any on-going pairing procedure started
    // using a previous delegate. Pairing requests will be rejected if no PairingDelegate has been
    // assigned.
    SetPairingDelegate(
        fuchsia.bluetooth.control.InputCapabilityType input,
        fuchsia.bluetooth.control.OutputCapabilityType output,
        fuchsia.bluetooth.control.PairingDelegate? delegate);

    // Adds existing bonded devices to the host. The host will be configured to automatically connect
    // to these devices when they are in range and connectable. Future connections will be encrypted
    // using the provided bonding data.
    AddBondedDevices(vector<BondingData> bonds) -> (fuchsia.bluetooth.Status status);

    // ===== Events =====

    // Notifies when the adapter state changes.
    -> OnAdapterStateChanged(fuchsia.bluetooth.control.AdapterState state);

    // Events that are sent when a connectable device is added, updated, or
    // removed as a result of connection and discovery procedures.
    -> OnDeviceUpdated(fuchsia.bluetooth.control.RemoteDevice device);
    -> OnDeviceRemoved(string identifier);

    // Notifies when bonding data for a device has been updated.
    -> OnNewBondingData(BondingData data);

    // TODO(BT-194): Introduce a "OnBondRemoved()" event to notify when existing
    // keys become stale.
};