sdk/fidl/fuchsia.bluetooth.host/host.fidl - fuchsia - Git at Google

 // 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();
 };

 /// 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);

     /// 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().
     flexible WatchPeers() -> (struct {
         updated vector<sys.Peer>:MAX;
         removed vector<bt.PeerId>:MAX;
     });

     /// 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;
     });

     /// 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.
     flexible RestoreBonds(struct {
         bonds vector<sys.BondingData>:MAX;
     }) -> (struct {
         errors vector<sys.BondingData>:MAX;
     });

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

     /// Notifies when bonding data for a peer has been updated.
     flexible -> OnNewBondingData(struct {
         data sys.BondingData;
     });

     // TODO(https://fxbug.dev/42158854): Introduce a "OnBondRemoved()" event to notify when existing
     // keys become stale.
 };
	// 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();
	};

	/// 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);

	/// 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().
	flexible WatchPeers() -> (struct {
	updated vector<sys.Peer>:MAX;
	removed vector<bt.PeerId>:MAX;
	});

	/// 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;
	});

	/// 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.
	flexible RestoreBonds(struct {
	bonds vector<sys.BondingData>:MAX;
	}) -> (struct {
	errors vector<sys.BondingData>:MAX;
	});

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

	/// Notifies when bonding data for a peer has been updated.
	flexible -> OnNewBondingData(struct {
	data sys.BondingData;
	});

	// TODO(https://fxbug.dev/42158854): Introduce a "OnBondRemoved()" event to notify when existing
	// keys become stale.
	};