// 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 as bt;
using fuchsia.bluetooth.sys as sys;

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

/// 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 host subsystem and controller managed by this Host
    /// instance. If there has been no change to the state since the last call to this method, the
    /// response will be deferred until there is a change.
    ///
    /// The returned `info` structure will be populated with the current state of the bt-host
    /// device. However the `active` parameter will never be populated. This field is managed
    /// by a higher layer.
    WatchState() -> (sys.HostInfo info);

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

    /// Monitors updates for connectable peers known to the system. Replies only when
    /// peers have been added, modified, or removed since the most recent call to WatchPeers().
    ///
    /// Peers are added and updated as new information is obtained during discovery, connection
    /// establishment, and bonding procedures.
    ///
    /// Peers are removed either:
    ///   a. explicitly via [`fuchsia.bluetooth.host.Host/Forget`], or
    ///   b. no transmission has been received from the peer for an internally determined duration
    ///      of time and the peer is neither connected nor bonded.
    ///
    /// - response `updated` Peers that were added or updated since the last call to WatchPeers().
    /// - response `removed` Ids of peers that were removed since the last call to WatchPeers().
    WatchPeers() -> (vector<sys.Peer> updated, vector<bt.PeerId> removed);

    /// Sets the local name for this host device.
    SetLocalName(string local_name) -> () error sys.Error;

    /// Sets the device class for this host device.
    SetDeviceClass(bt.DeviceClass device_class) -> () error sys.Error;

    /// Initiates a general discovery procedure for BR/EDR and LE devices. On success, discovered
    /// peers can be monitored using the [`fuchsia.bluetooth.host/Host.WatchPeers`] method.
    ///
    /// 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 Host protocol
    /// channel gets closed. If the device does not support BR/EDR, only LE discovery will be
    /// performed.
    StartDiscovery() -> () error sys.Error;

    /// Terminates discovery if one was started via StartDiscovery().
    ///
    /// 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();

    /// Sets whether this host should be connectable.
    SetConnectable(bool enabled) -> () error sys.Error;

    /// Sets whether this host should be discoverable.
    SetDiscoverable(bool enabled) -> () error sys.Error;

    /// Establish a BR/EDR and/or LE connection to the peer with identifier `id`:
    ///
    ///   - If the peer 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 peer 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(bt.PeerId id) -> () error sys.Error;

    /// Terminate all connections (BR/EDR or LE) to the remote peer with identifier `id`.
    ///
    /// + request `id` The identifier of the peer to disconnect.
    /// - response `status` Contains an error if either LE or BR/EDR transport fails to disconnect. Contains
    ///                     success when both transports are successfully disconnected or if the peer is already
    ///                     disconnected.
    Disconnect(bt.PeerId id) -> () error sys.Error;

    /// Initiates pairing to the peer with the supplied `id` and `options`. Returns an error
    /// variant of fuchsia.bluetooth.Status if no connected peer with `id` is found or the pairing
    /// procedure fails. If already paired, this will do nothing unless the pairing is over LE and
    /// the PairingOptions.le_security_level is more secure than the current security level.
    ///
    /// NOTE: This is intended to satisfy test scenarios that require pairing procedures to be
    /// initiated without relying on service access. In normal operation, Bluetooth security is
    /// enforced during service access.
    Pair(fuchsia.bluetooth.PeerId id, fuchsia.bluetooth.control.PairingOptions options) -> () error sys.Error;

    /// Deletes a peer from the Bluetooth host. If the peer is connected, it will be disconnected.
    /// `device_id` will no longer refer to any peer, even if a device with the same address is
    /// discovered again.
    ///
    /// Returns success after no peer exists that's identified by `device_id` (even if it didn't
    /// exist before Forget), failure if the peer specified by `device_id` could not be
    /// disconnected or deleted and still exists.
    Forget(bt.PeerId id) -> () error sys.Error;

    /// 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<fuchsia.bluetooth.control.BondingData> bonds) -> (fuchsia.bluetooth.Status status);

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

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

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