// 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.gatt;
using fuchsia.bluetooth.gatt2;
using fuchsia.bluetooth.le;

/// Receives a bt-host by protocol for use in the Bluetooth Host Subsystem
@discoverable
open protocol Receiver {
    /// Adds a new bt-host. If `request` cannot be handled, it should be closed.
    flexible AddHost(resource struct {
        request client_end:Host;
    });
};

type ProtocolRequest = flexible resource union {
    1: central server_end:fuchsia.bluetooth.le.Central;
    2: peripheral server_end:fuchsia.bluetooth.le.Peripheral;
    3: gatt_server server_end:fuchsia.bluetooth.gatt.Server;
    4: gatt2_server server_end:fuchsia.bluetooth.gatt2.Server;
    5: profile server_end:fuchsia.bluetooth.bredr.Profile;
};

/// A token protocol representing discovery being enabled.
open protocol DiscoverySession {
    /// Closes this DiscoverySession on the server end, ending discovery if this is the last open
    /// DiscoverySession. This can be used to synchronize the closure on both ends of the protocol.
    /// If synchronization is not required, the DiscoverySession protocol can simply be closed
    /// instead.
    flexible Stop();
};

open protocol BondingDelegate {
    /// Restores existing bonded devices to the host. An authenticated session will be established
    /// for future connections using the provided bonding data.
    ///
    /// If bonding data for the LE transport is available, then the host will establish a connection
    /// if the peer directs connectable advertisements to us.
    ///
    /// If any of the entries in `bonds` could not be restored, then they will be returned in
    /// `errors`. This can happen for entries that are malformed and for peers that are already
    /// known to the bt-host. An empty `errors` list indicates that all bonds were successfully
    /// restored.
    flexible RestoreBonds(struct {
        bonds vector<sys.BondingData>:MAX;
    }) -> (struct {
        errors vector<sys.BondingData>:MAX;
    });

    /// Get the next bonding update. The request will hang until the next update.
    flexible WatchBonds() -> (flexible union {
        /// Notifies when bonding data for a peer has been added/updated.
        1: updated sys.BondingData;
        /// Notifies when a bond is removed due to authentication failures.
        2: removed bt.PeerId;
    });
};

open protocol PeerWatcher {
    /// Get the next peer update. The request will hang until the next update.
    flexible GetNext() -> (flexible union {
        /// Peers are added and updated as new information is obtained during discovery, connection
        /// establishment, and bonding procedures.
        1: updated vector<sys.Peer>:MAX;
        /// Peers are removed either:
        ///   a. explicitly via [`fuchsia.bluetooth.host.Host/Forget`], or
        ///   b. bt-host has not seen the peer recently and the peer is not bonded or connected
        2: removed vector<bt.PeerId>:MAX;
    });
};

/// Interface for interacting with a Bluetooth host device (bt-host)
open protocol Host {
    /// Fulfills a given protocol request. bt-host will start processing FIDL messages. If the
    /// request cannot be fulfilled, the bt-host device will close its end of the given channel.
    flexible RequestProtocol(ProtocolRequest);

    /// 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.
    ///
    /// The Host protocol will close when shutdown is complete.
    strict Shutdown();

    /// 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.
    flexible WatchState() -> (struct {
        info sys.HostInfo;
    });

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

    /// Sets a PeerWatcher protocol that will be notified of changes to peers.
    /// Only 1 PeerWatcher can be configured at a time.
    // TODO(https://fxbug.dev/340585537): Support multiple PeerWatchers.
    flexible SetPeerWatcher(resource struct {
        peer_watcher server_end:PeerWatcher;
    });

    /// Sets the local name for this host device.
    flexible SetLocalName(struct {
        local_name bt.DeviceName;
    }) -> () error sys.Error;

    /// Sets the device class for this host device.
    flexible SetDeviceClass(struct {
        device_class bt.DeviceClass;
    }) -> () 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 Error,
    /// an epitaph will be returned from `token`. If the device does not support BR/EDR, only LE
    /// discovery will be performed.
    ///
    /// On the LE transport, only general-discoverable and connectable peripherals will be reported.
    ///
    /// Discovery will continue until all discovery sessions are closed.
    ///
    /// + request `token` The DiscoverySession protocol that must be held open as long as
    ///     discovery should be enabled. Closing it will stop discovery if no other sessions
    ///     are open.
    flexible StartDiscovery(resource table {
        /// Required.
        1: token server_end:DiscoverySession;
    });

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

    /// Sets whether this host should be discoverable.
    flexible SetDiscoverable(struct {
        enabled bool;
    }) -> () 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.
    flexible Connect(struct {
        id bt.PeerId;
    }) -> () 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.
    flexible Disconnect(struct {
        id bt.PeerId;
    }) -> () error sys.Error;

    /// Initiates pairing to the peer with the supplied `id` and `options`. Returns an error if no
    /// connected peer with `id` is found or the pairing procedure fails.
    ///
    /// If `options` specifies a higher security level than the current pairing, this method
    /// attempts to raise the security level. Otherwise this method has no effect and returns
    /// success.
    ///
    /// 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.
    flexible Pair(struct {
        id bt.PeerId;
        options sys.PairingOptions;
    }) -> () 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.
    flexible Forget(struct {
        id bt.PeerId;
    }) -> () 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.
    flexible EnableBackgroundScan(struct {
        enabled bool;
    });

    /// 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).
    strict EnablePrivacy(struct {
        enabled bool;
    });

    /// Set the GAP BR/EDR Security Mode of the host. bt-host only supports encrypted,
    /// connection-based security modes, i.e. Mode 4 and Secure Connections Only mode. If the
    /// security mode is set to Secure Connections Only, any existing encrypted connections which
    /// do not meet the security requirements of Secure Connections Only mode will be disconnected.
    strict SetBrEdrSecurityMode(struct {
        bredr_security_mode sys.BrEdrSecurityMode;
    });

    /// Set the GAP LE Security Mode of the host. bt-host only supports encrypted, connection-based
    /// security modes, i.e. Mode 1 and Secure Connections Only mode. If the security mode is set
    /// to Secure Connections Only, any existing encrypted connections which do not meet the
    /// security requirements of Secure Connections Only mode will be disconnected.
    strict SetLeSecurityMode(struct {
        le_security_mode sys.LeSecurityMode;
    });

    /// Assigns the pairing delegate that will respond to authentication challenges using the given
    /// I/O capabilities. Calling this method cancels any on-going pairing procedure started
    /// using a previous delegate. Pairing requests will be rejected if no PairingDelegate has been
    /// assigned.
    flexible SetPairingDelegate(resource struct {
        input sys.InputCapability;
        output sys.OutputCapability;
        delegate client_end:sys.PairingDelegate;
    });

    /// Set a BondingDelegate protocol that will be notified of new and removed bonds that need to
    /// be persisted. If a delegate is already set, the new `delegate` will be closed with
    /// ALREADY_BOUND
    flexible SetBondingDelegate(resource struct {
        delegate server_end:BondingDelegate;
    });
};