bluetooth_device_client.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310
  1. // Copyright 2013 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef DEVICE_BLUETOOTH_DBUS_BLUETOOTH_DEVICE_CLIENT_H_
  5. #define DEVICE_BLUETOOTH_DBUS_BLUETOOTH_DEVICE_CLIENT_H_
  6. #include <stdint.h>
  7. #include <map>
  8. #include <string>
  9. #include <vector>
  10. #include "base/callback.h"
  11. #include "dbus/object_path.h"
  12. #include "dbus/property.h"
  13. #include "device/bluetooth/bluetooth_export.h"
  14. #include "device/bluetooth/bluez/bluetooth_service_record_bluez.h"
  15. #include "device/bluetooth/dbus/bluez_dbus_client.h"
  16. namespace bluez {
  17. // BluetoothDeviceClient is used to communicate with objects representing
  18. // remote Bluetooth Devices.
  19. class DEVICE_BLUETOOTH_EXPORT BluetoothDeviceClient : public BluezDBusClient {
  20. public:
  21. using ServiceRecordList = std::vector<BluetoothServiceRecordBlueZ>;
  22. // This callback invoked for a successful GetConnInfo API call with the
  23. // RSSI, TX power, and maximum TX power of the current connection.
  24. using ConnInfoCallback = base::OnceCallback<
  25. void(int16_t rssi, int16_t transmit_power, int16_t max_transmit_power)>;
  26. // This callback invoked for a successful GetServiceRecords API call with the
  27. // currently discovered service records.
  28. using ServiceRecordsCallback =
  29. base::OnceCallback<void(const ServiceRecordList&)>;
  30. // The ErrorCallback is used by device methods to indicate failure.
  31. // It receives two arguments: the name of the error in |error_name| and
  32. // an optional message in |error_message|.
  33. using ErrorCallback =
  34. base::OnceCallback<void(const std::string& error_name,
  35. const std::string& error_message)>;
  36. // Structure of properties associated with bluetooth devices.
  37. struct Properties : public dbus::PropertySet {
  38. // The Bluetooth device address of the device. Read-only.
  39. dbus::Property<std::string> address;
  40. // The Bluetooth address type of the device. Read-only.
  41. dbus::Property<std::string> address_type;
  42. // The Bluetooth friendly name of the device. Read-only, to give a
  43. // different local name, use the |alias| property.
  44. dbus::Property<std::string> name;
  45. // Proposed icon name for the device according to the freedesktop.org
  46. // icon naming specification. Read-only.
  47. dbus::Property<std::string> icon;
  48. // The Bluetooth class of the device. Read-only.
  49. dbus::Property<uint32_t> bluetooth_class;
  50. // The transport type of the device. Read-only.
  51. dbus::Property<std::string> type;
  52. // The GAP external appearance of the device. Read-only.
  53. dbus::Property<uint16_t> appearance;
  54. // Unique numeric identifier for the vendor of the device. Read-only.
  55. dbus::Property<uint16_t> vendor;
  56. // List of 128-bit UUIDs that represent the available remote services.
  57. // Read-only.
  58. dbus::Property<std::vector<std::string>> uuids;
  59. // Transmitted power level. This field is avaliable only for LE devices
  60. // that include this field in AD. Read-only.
  61. dbus::Property<int16_t> tx_power;
  62. // Indicates that the device is currently paired. Read-only.
  63. dbus::Property<bool> paired;
  64. // Indicates that the device is currently connected via any transports.
  65. // Read-only.
  66. dbus::Property<bool> connected;
  67. // Indicates that the device is currently connected via BLE. Read-only.
  68. dbus::Property<bool> connected_le;
  69. // Whether the device is trusted, and connections should be always
  70. // accepted and attempted when the device is visible.
  71. dbus::Property<bool> trusted;
  72. // Whether the device is blocked, connections will be always rejected
  73. // and the device will not be visible.
  74. dbus::Property<bool> blocked;
  75. // Local alias for the device, if not set, is equal to |name|.
  76. dbus::Property<std::string> alias;
  77. // Object path of the adapter the device belongs to. Read-only.
  78. dbus::Property<dbus::ObjectPath> adapter;
  79. // Indicates whether the device is likely to only support pre-2.1
  80. // PIN Code pairing rather than 2.1 Secure Simple Pairing, this can
  81. // give false positives. Read-only.
  82. dbus::Property<bool> legacy_pairing;
  83. // Remote Device ID information in Linux kernel modalias format. Read-only.
  84. dbus::Property<std::string> modalias;
  85. // Received signal strength indicator that is set when the device is
  86. // discovered during inquiry. Read-only.
  87. dbus::Property<int16_t> rssi;
  88. // Manufacturer specific advertisement data. Keys are 16 bits Manufacturer
  89. // ID followed by its byte array value. Read-only.
  90. dbus::Property<std::map<uint16_t, std::vector<uint8_t>>> manufacturer_data;
  91. // Service advertisement data. Keys are the UUIDs in string format followed
  92. // by its byte array value. Read-only.
  93. dbus::Property<std::map<std::string, std::vector<uint8_t>>> service_data;
  94. // Indicate whether or not service discovery has been resolved. Read-only.
  95. dbus::Property<bool> services_resolved;
  96. // The Advertising Data Flags of the remote device. Read-only.
  97. dbus::Property<std::vector<uint8_t>> advertising_data_flags;
  98. // The MTU used in ATT communication with the remote device. Read-only.
  99. dbus::Property<uint16_t> mtu;
  100. // The EIR advertised by the remote device. Read-only.
  101. dbus::Property<std::vector<uint8_t>> eir;
  102. Properties(dbus::ObjectProxy* object_proxy,
  103. const std::string& interface_name,
  104. const PropertyChangedCallback& callback);
  105. ~Properties() override;
  106. };
  107. // Connection parameters that can be passed to SetLEConnectionParameters().
  108. struct ConnectionParameters {
  109. // The lower bound to request for the connection interval.
  110. // In units of 1.25ms.
  111. uint16_t min_connection_interval;
  112. // The upper bound to request for the connection interval.
  113. // In units of 1.25ms.
  114. uint16_t max_connection_interval;
  115. };
  116. // Interface for observing changes from a remote bluetooth device.
  117. class Observer {
  118. public:
  119. virtual ~Observer() {}
  120. // Called when the remote device with object path |object_path| is added
  121. // to the set of known devices.
  122. virtual void DeviceAdded(const dbus::ObjectPath& object_path) {}
  123. // Called when the remote device with object path |object_path| is removed
  124. // from the set of known devices.
  125. virtual void DeviceRemoved(const dbus::ObjectPath& object_path) {}
  126. // Called when the device with object path |object_path| has a
  127. // change in value of the property named |property_name|.
  128. virtual void DevicePropertyChanged(const dbus::ObjectPath& object_path,
  129. const std::string& property_name) {}
  130. };
  131. BluetoothDeviceClient(const BluetoothDeviceClient&) = delete;
  132. BluetoothDeviceClient& operator=(const BluetoothDeviceClient&) = delete;
  133. ~BluetoothDeviceClient() override;
  134. // Adds and removes observers for events on all remote bluetooth
  135. // devices. Check the |object_path| parameter of observer methods to
  136. // determine which device is issuing the event.
  137. virtual void AddObserver(Observer* observer) = 0;
  138. virtual void RemoveObserver(Observer* observer) = 0;
  139. // Returns the list of device object paths associated with the given adapter
  140. // identified by the D-Bus object path |adapter_path|.
  141. virtual std::vector<dbus::ObjectPath> GetDevicesForAdapter(
  142. const dbus::ObjectPath& adapter_path) = 0;
  143. // Obtain the properties for the device with object path |object_path|,
  144. // any values should be copied if needed.
  145. virtual Properties* GetProperties(const dbus::ObjectPath& object_path) = 0;
  146. // Connects to the device with object path |object_path|, connecting any
  147. // profiles that can be connected to and have been flagged as auto-connected;
  148. // may be used to connect additional profiles for an already connected device,
  149. // and succeeds if at least one profile is connected.
  150. virtual void Connect(const dbus::ObjectPath& object_path,
  151. base::OnceClosure callback,
  152. ErrorCallback error_callback) = 0;
  153. // Connects to the device with object path |object_path| via classic
  154. // Bluetooth, connecting any profiles that can be connected to and have been
  155. // flagged as auto-connected; may be used to connect additional profiles for
  156. // an already connected device, and succeeds if at least one profile is
  157. // connected.
  158. virtual void ConnectClassic(const dbus::ObjectPath& object_path,
  159. base::OnceClosure callback,
  160. ErrorCallback error_callback) = 0;
  161. // Connects to the device with object path |object_path| via BLE,
  162. // connecting any profiles that can be connected to and have been flagged as
  163. // auto-connected; may be used to connect additional profiles for an already
  164. // connected device, and succeeds if at least one profile is connected.
  165. virtual void ConnectLE(const dbus::ObjectPath& object_path,
  166. base::OnceClosure callback,
  167. ErrorCallback error_callback) = 0;
  168. // Disconnects all connections to the device with object path |object_path|,
  169. // terminating the low-level ACL connection and any profiles using it.
  170. virtual void Disconnect(const dbus::ObjectPath& object_path,
  171. base::OnceClosure callback,
  172. ErrorCallback error_callback) = 0;
  173. // Disconnects the BLE connection to the device with object path
  174. // |object_path|, terminating the low-level ACL connection and any profiles
  175. // using it.
  176. virtual void DisconnectLE(const dbus::ObjectPath& object_path,
  177. base::OnceClosure callback,
  178. ErrorCallback error_callback) = 0;
  179. // Connects to the profile |uuid| on the device with object path
  180. // |object_path|, provided that the profile has been registered with a
  181. // handler on the local device.
  182. virtual void ConnectProfile(const dbus::ObjectPath& object_path,
  183. const std::string& uuid,
  184. base::OnceClosure callback,
  185. ErrorCallback error_callback) = 0;
  186. // Disconnects from the profile |uuid| on the device with object path
  187. // |object_path|.
  188. virtual void DisconnectProfile(const dbus::ObjectPath& object_path,
  189. const std::string& uuid,
  190. base::OnceClosure callback,
  191. ErrorCallback error_callback) = 0;
  192. // Initiates pairing with the device with object path |object_path| and
  193. // retrieves all SDP records or GATT primary services. An agent must be
  194. // registered to handle the pairing request.
  195. virtual void Pair(const dbus::ObjectPath& object_path,
  196. base::OnceClosure callback,
  197. ErrorCallback error_callback) = 0;
  198. // Cancels an in-progress pairing with the device with object path
  199. // |object_path| initiated by Pair().
  200. virtual void CancelPairing(const dbus::ObjectPath& object_path,
  201. base::OnceClosure callback,
  202. ErrorCallback error_callback) = 0;
  203. // Returns the RSSI, TX power, and maximum TX power of a connection to the
  204. // device with object path |object_path|. If the device is not connected, then
  205. // an error will be returned.
  206. virtual void GetConnInfo(const dbus::ObjectPath& object_path,
  207. ConnInfoCallback callback,
  208. ErrorCallback error_callback) = 0;
  209. // Sets the connection parameters (e.g. connection interval) for the device.
  210. virtual void SetLEConnectionParameters(
  211. const dbus::ObjectPath& object_path,
  212. const ConnectionParameters& conn_params,
  213. base::OnceClosure callback,
  214. ErrorCallback error_callback) = 0;
  215. // Returns the currently discovered service records for the device with
  216. // object path |object_path|. If the device is not connected, then an error
  217. // will be returned.
  218. virtual void GetServiceRecords(const dbus::ObjectPath& object_path,
  219. ServiceRecordsCallback callback,
  220. ErrorCallback error_callback) = 0;
  221. // Executes all the privous prepare writes in a reliable write session.
  222. virtual void ExecuteWrite(const dbus::ObjectPath& object_path,
  223. base::OnceClosure callback,
  224. ErrorCallback error_callback) = 0;
  225. // Aborts all the privous prepare writes in a reliable write session.
  226. virtual void AbortWrite(const dbus::ObjectPath& object_path,
  227. base::OnceClosure callback,
  228. ErrorCallback error_callback) = 0;
  229. // Creates the instance.
  230. static BluetoothDeviceClient* Create();
  231. // Constants used to indicate exceptional error conditions.
  232. static const char kNoResponseError[];
  233. static const char kUnknownDeviceError[];
  234. // Strings used by BlueZ for the transport type of the remote device.
  235. // See https://chromium-review.googlesource.com/c/351512/
  236. static const char kTypeBredr[];
  237. static const char kTypeLe[];
  238. static const char kTypeDual[];
  239. protected:
  240. BluetoothDeviceClient();
  241. };
  242. } // namespace bluez
  243. #endif // DEVICE_BLUETOOTH_DBUS_BLUETOOTH_DEVICE_CLIENT_H_