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