blob: a03abc42f6823f5f6fba10038f7b00c90e8483ab [file] [log] [blame]
// 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.
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;
/// Interface for interacting with a Bluetooth host device (bt-host)
closed 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.
strict RequestLowEnergyCentral(resource struct {
central server_end:fuchsia.bluetooth.le.Central;
strict RequestLowEnergyPeripheral(resource struct {
peripheral server_end:fuchsia.bluetooth.le.Peripheral;
strict RequestGattServer(resource struct {
server server_end:fuchsia.bluetooth.gatt.Server;
strict RequestGatt2Server(resource struct {
server server_end:fuchsia.bluetooth.gatt2.Server;
strict RequestProfile(resource struct {
profile server_end:fuchsia.bluetooth.bredr.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.
strict 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.
strict WatchState() -> (struct {
info sys.HostInfo;
/// Assigns local data to this host.
strict SetLocalData(struct {
host_data sys.HostData;
/// 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 [``], 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().
strict WatchPeers() -> (struct {
updated vector<sys.Peer>:MAX;
removed vector<bt.PeerId>:MAX;
/// Sets the local name for this host device.
strict SetLocalName(struct {
local_name bt.DeviceName;
}) -> () error sys.Error;
/// Sets the device class for this host device.
strict 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 [``] 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.
strict 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.
strict StopDiscovery();
/// Sets whether this host should be connectable.
strict SetConnectable(struct {
enabled bool;
}) -> () error sys.Error;
/// Sets whether this host should be discoverable.
strict 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.
strict 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.
strict 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.
strict 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.
strict 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.
strict 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.
strict SetPairingDelegate(resource struct {
input sys.InputCapability;
output sys.OutputCapability;
delegate client_end:sys.PairingDelegate;
/// 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 automatically
/// establish a connection when the peer is in range and connectable.
/// 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.
strict RestoreBonds(struct {
bonds vector<sys.BondingData>:MAX;
}) -> (struct {
errors vector<sys.BondingData>:MAX;
// ===== Events =====
/// Notifies when bonding data for a peer has been updated.
strict -> OnNewBondingData(struct {
data sys.BondingData;
// TODO( Introduce a "OnBondRemoved()" event to notify when existing
// keys become stale.