bluetooth_device.h revision 010d83a9304c5a91596085d917d248abff47903a
1// Copyright (c) 2012 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 5#ifndef DEVICE_BLUETOOTH_BLUETOOTH_DEVICE_H_ 6#define DEVICE_BLUETOOTH_BLUETOOTH_DEVICE_H_ 7 8#include <map> 9#include <string> 10#include <vector> 11 12#include "base/callback.h" 13#include "base/memory/ref_counted.h" 14#include "base/memory/scoped_vector.h" 15#include "base/strings/string16.h" 16#include "device/bluetooth/bluetooth_uuid.h" 17#include "net/base/net_log.h" 18 19namespace device { 20 21class BluetoothGattService; 22class BluetoothProfile; 23class BluetoothSocket; 24class BluetoothUUID; 25 26struct BluetoothOutOfBandPairingData; 27 28// BluetoothDevice represents a remote Bluetooth device, both its properties and 29// capabilities as discovered by a local adapter and actions that may be 30// performed on the remove device such as pairing, connection and disconnection. 31// 32// The class is instantiated and managed by the BluetoothAdapter class 33// and pointers should only be obtained from that class and not cached, 34// instead use the GetAddress() method as a unique key for a device. 35// 36// Since the lifecycle of BluetoothDevice instances is managed by 37// BluetoothAdapter, that class rather than this provides observer methods 38// for devices coming and going, as well as properties being updated. 39class BluetoothDevice { 40 public: 41 // Possible values that may be returned by GetVendorIDSource(), 42 // indicating different organisations that allocate the identifiers returned 43 // by GetVendorID(). 44 enum VendorIDSource { 45 VENDOR_ID_UNKNOWN, 46 VENDOR_ID_BLUETOOTH, 47 VENDOR_ID_USB 48 }; 49 50 // Possible values that may be returned by GetDeviceType(), representing 51 // different types of bluetooth device that we support or are aware of 52 // decoded from the bluetooth class information. 53 enum DeviceType { 54 DEVICE_UNKNOWN, 55 DEVICE_COMPUTER, 56 DEVICE_PHONE, 57 DEVICE_MODEM, 58 DEVICE_AUDIO, 59 DEVICE_CAR_AUDIO, 60 DEVICE_VIDEO, 61 DEVICE_PERIPHERAL, 62 DEVICE_JOYSTICK, 63 DEVICE_GAMEPAD, 64 DEVICE_KEYBOARD, 65 DEVICE_MOUSE, 66 DEVICE_TABLET, 67 DEVICE_KEYBOARD_MOUSE_COMBO 68 }; 69 70 // The value returned if the RSSI or transmit power cannot be read. 71 static const int kUnknownPower = 127; 72 73 // Possible errors passed back to an error callback function in case of a 74 // failed call to Connect(). 75 enum ConnectErrorCode { 76 ERROR_UNKNOWN, 77 ERROR_INPROGRESS, 78 ERROR_FAILED, 79 ERROR_AUTH_FAILED, 80 ERROR_AUTH_CANCELED, 81 ERROR_AUTH_REJECTED, 82 ERROR_AUTH_TIMEOUT, 83 ERROR_UNSUPPORTED_DEVICE 84 }; 85 86 // Interface for observing changes from bluetooth devices. 87 class Observer { 88 public: 89 virtual ~Observer() {} 90 91 // Called when a new GATT service |service| is added to the device |device|, 92 // as the service is received from the device. Don't cache |service|. Store 93 // its identifier instead (i.e. BluetoothGattService::GetIdentifier). 94 virtual void GattServiceAdded(BluetoothDevice* device, 95 BluetoothGattService* service) {} 96 97 // Called when the GATT service |service| is removed from the device 98 // |device|. This can happen if the attribute database of the remote device 99 // changes or when |device| gets removed. 100 virtual void GattServiceRemoved(BluetoothDevice* device, 101 BluetoothGattService* service) {} 102 103 // TODO(keybuk): add observers for pairing and connection. 104 }; 105 106 // Interface for negotiating pairing of bluetooth devices. 107 class PairingDelegate { 108 public: 109 virtual ~PairingDelegate() {} 110 111 // This method will be called when the Bluetooth daemon requires a 112 // PIN Code for authentication of the device |device|, the delegate should 113 // obtain the code from the user and call SetPinCode() on the device to 114 // provide it, or RejectPairing() or CancelPairing() to reject or cancel 115 // the request. 116 // 117 // PIN Codes are generally required for Bluetooth 2.0 and earlier devices 118 // for which there is no automatic pairing or special handling. 119 virtual void RequestPinCode(BluetoothDevice* device) = 0; 120 121 // This method will be called when the Bluetooth daemon requires a 122 // Passkey for authentication of the device |device|, the delegate should 123 // obtain the passkey from the user (a numeric in the range 0-999999) and 124 // call SetPasskey() on the device to provide it, or RejectPairing() or 125 // CancelPairing() to reject or cancel the request. 126 // 127 // Passkeys are generally required for Bluetooth 2.1 and later devices 128 // which cannot provide input or display on their own, and don't accept 129 // passkey-less pairing. 130 virtual void RequestPasskey(BluetoothDevice* device) = 0; 131 132 // This method will be called when the Bluetooth daemon requires that the 133 // user enter the PIN code |pincode| into the device |device| so that it 134 // may be authenticated. 135 // 136 // This is used for Bluetooth 2.0 and earlier keyboard devices, the 137 // |pincode| will always be a six-digit numeric in the range 000000-999999 138 // for compatibility with later specifications. 139 virtual void DisplayPinCode(BluetoothDevice* device, 140 const std::string& pincode) = 0; 141 142 // This method will be called when the Bluetooth daemon requires that the 143 // user enter the Passkey |passkey| into the device |device| so that it 144 // may be authenticated. 145 // 146 // This is used for Bluetooth 2.1 and later devices that support input 147 // but not display, such as keyboards. The Passkey is a numeric in the 148 // range 0-999999 and should be always presented zero-padded to six 149 // digits. 150 virtual void DisplayPasskey(BluetoothDevice* device, 151 uint32 passkey) = 0; 152 153 // This method will be called when the Bluetooth daemon gets a notification 154 // of a key entered on the device |device| while pairing with the device 155 // using a PIN code or a Passkey. 156 // 157 // This method will be called only after DisplayPinCode() or 158 // DisplayPasskey() method is called, but is not warranted to be called 159 // on every pairing process that requires a PIN code or a Passkey because 160 // some device may not support this feature. 161 // 162 // The |entered| value describes the number of keys entered so far, 163 // including the last [enter] key. A first call to KeysEntered() with 164 // |entered| as 0 will be sent when the device supports this feature. 165 virtual void KeysEntered(BluetoothDevice* device, 166 uint32 entered) = 0; 167 168 // This method will be called when the Bluetooth daemon requires that the 169 // user confirm that the Passkey |passkey| is displayed on the screen 170 // of the device |device| so that it may be authenticated. The delegate 171 // should display to the user and ask for confirmation, then call 172 // ConfirmPairing() on the device to confirm, RejectPairing() on the device 173 // to reject or CancelPairing() on the device to cancel authentication 174 // for any other reason. 175 // 176 // This is used for Bluetooth 2.1 and later devices that support display, 177 // such as other computers or phones. The Passkey is a numeric in the 178 // range 0-999999 and should be always present zero-padded to six 179 // digits. 180 virtual void ConfirmPasskey(BluetoothDevice* device, 181 uint32 passkey) = 0; 182 183 // This method will be called when the Bluetooth daemon requires that a 184 // pairing request, usually only incoming, using the just-works model is 185 // authorized. The delegate should decide whether the user should confirm 186 // or not, then call ConfirmPairing() on the device to confirm the pairing 187 // (whether by user action or by default), RejectPairing() on the device to 188 // reject or CancelPairing() on the device to cancel authorization for 189 // any other reason. 190 virtual void AuthorizePairing(BluetoothDevice* device) = 0; 191 }; 192 193 virtual ~BluetoothDevice(); 194 195 // Adds and removes observers for events on this Bluetooth device. If 196 // monitoring multiple devices, check the |device| parameter of the observer 197 // methods to determine which device is issuing the event. 198 virtual void AddObserver(Observer* observer) = 0; 199 virtual void RemoveObserver(Observer* observer) = 0; 200 201 // Returns the Bluetooth class of the device, used by GetDeviceType() 202 // and metrics logging, 203 virtual uint32 GetBluetoothClass() const = 0; 204 205 // Returns the Bluetooth of address the device. This should be used as 206 // a unique key to identify the device and copied where needed. 207 virtual std::string GetAddress() const = 0; 208 209 // Returns the allocation source of the identifier returned by GetVendorID(), 210 // where available, or VENDOR_ID_UNKNOWN where not. 211 virtual VendorIDSource GetVendorIDSource() const = 0; 212 213 // Returns the Vendor ID of the device, where available. 214 virtual uint16 GetVendorID() const = 0; 215 216 // Returns the Product ID of the device, where available. 217 virtual uint16 GetProductID() const = 0; 218 219 // Returns the Device ID of the device, typically the release or version 220 // number in BCD format, where available. 221 virtual uint16 GetDeviceID() const = 0; 222 223 // Returns the name of the device suitable for displaying, this may 224 // be a synthesized string containing the address and localized type name 225 // if the device has no obtained name. 226 virtual base::string16 GetName() const; 227 228 // Returns the type of the device, limited to those we support or are 229 // aware of, by decoding the bluetooth class information. The returned 230 // values are unique, and do not overlap, so DEVICE_KEYBOARD is not also 231 // DEVICE_PERIPHERAL. 232 DeviceType GetDeviceType() const; 233 234 // Gets the "received signal strength indication" (RSSI) of the current 235 // connection to the device. The RSSI indicates the power present in the 236 // received radio signal, measured in dBm, to a resolution of 1dBm. Larger 237 // (typically, less negative) values indicate a stronger signal. 238 // If the device is not currently connected, then returns the RSSI read from 239 // the last inquiry that returned the device, where available. In case of an 240 // error, returns |kUnknownPower|. Otherwise, returns the connection's RSSI. 241 virtual int GetRSSI() const = 0; 242 243 // These two methods are used to read the current or maximum transmit power 244 // ("Tx power") of the current connection to the device. The transmit power 245 // indicates the strength of the signal broadcast from the host's Bluetooth 246 // antenna when communicating with the device, measured in dBm, to a 247 // resolution of 1dBm. Larger (typically, less negative) values 248 // indicate a stronger signal. 249 // It is only meaningful to call this method when there is a connection 250 // established to the device. If there is no connection, or in case of an 251 // error, returns |kUnknownPower|. Otherwise, returns the connection's 252 // transmit power. 253 virtual int GetCurrentHostTransmitPower() const = 0; 254 virtual int GetMaximumHostTransmitPower() const = 0; 255 256 // Indicates whether the device is known to support pairing based on its 257 // device class and address. 258 bool IsPairable() const; 259 260 // Indicates whether the device is paired with the adapter. 261 virtual bool IsPaired() const = 0; 262 263 // Indicates whether the device is currently connected to the adapter. 264 // Note that if IsConnected() is true, does not imply that the device is 265 // connected to any application or service. If the device is not paired, it 266 // could be still connected to the adapter for other reason, for example, to 267 // request the adapter's SDP records. The same holds for paired devices, since 268 // they could be connected to the adapter but not to an application. 269 virtual bool IsConnected() const = 0; 270 271 // Indicates whether the paired device accepts connections initiated from the 272 // adapter. This value is undefined for unpaired devices. 273 virtual bool IsConnectable() const = 0; 274 275 // Indicates whether there is a call to Connect() ongoing. For this attribute, 276 // we consider a call is ongoing if none of the callbacks passed to Connect() 277 // were called after the corresponding call to Connect(). 278 virtual bool IsConnecting() const = 0; 279 280 // Returns the set of UUIDs that this device supports. For classic Bluetooth 281 // devices this data is collected from both the EIR data and SDP tables, 282 // for Low Energy devices this data is collected from AD and GATT primary 283 // services, for dual mode devices this may be collected from both./ 284 typedef std::vector<BluetoothUUID> UUIDList; 285 virtual UUIDList GetUUIDs() const = 0; 286 287 // The ErrorCallback is used for methods that can fail in which case it 288 // is called, in the success case the callback is simply not called. 289 typedef base::Callback<void()> ErrorCallback; 290 291 // The ConnectErrorCallback is used for methods that can fail with an error, 292 // passed back as an error code argument to this callback. 293 // In the success case this callback is not called. 294 typedef base::Callback<void(enum ConnectErrorCode)> ConnectErrorCallback; 295 296 // Indicates whether the device is currently pairing and expecting a 297 // PIN Code to be returned. 298 virtual bool ExpectingPinCode() const = 0; 299 300 // Indicates whether the device is currently pairing and expecting a 301 // Passkey to be returned. 302 virtual bool ExpectingPasskey() const = 0; 303 304 // Indicates whether the device is currently pairing and expecting 305 // confirmation of a displayed passkey. 306 virtual bool ExpectingConfirmation() const = 0; 307 308 // Initiates a connection to the device, pairing first if necessary. 309 // 310 // Method calls will be made on the supplied object |pairing_delegate| 311 // to indicate what display, and in response should make method calls 312 // back to the device object. Not all devices require user responses 313 // during pairing, so it is normal for |pairing_delegate| to receive no 314 // calls. To explicitly force a low-security connection without bonding, 315 // pass NULL, though this is ignored if the device is already paired. 316 // 317 // If the request fails, |error_callback| will be called; otherwise, 318 // |callback| is called when the request is complete. 319 // After calling Connect, CancelPairing should be called to cancel the pairing 320 // process and release the pairing delegate if user cancels the pairing and 321 // closes the pairing UI. 322 virtual void Connect(PairingDelegate* pairing_delegate, 323 const base::Closure& callback, 324 const ConnectErrorCallback& error_callback) = 0; 325 326 // Sends the PIN code |pincode| to the remote device during pairing. 327 // 328 // PIN Codes are generally required for Bluetooth 2.0 and earlier devices 329 // for which there is no automatic pairing or special handling. 330 virtual void SetPinCode(const std::string& pincode) = 0; 331 332 // Sends the Passkey |passkey| to the remote device during pairing. 333 // 334 // Passkeys are generally required for Bluetooth 2.1 and later devices 335 // which cannot provide input or display on their own, and don't accept 336 // passkey-less pairing, and are a numeric in the range 0-999999. 337 virtual void SetPasskey(uint32 passkey) = 0; 338 339 // Confirms to the remote device during pairing that a passkey provided by 340 // the ConfirmPasskey() delegate call is displayed on both devices. 341 virtual void ConfirmPairing() = 0; 342 343 // Rejects a pairing or connection request from a remote device. 344 virtual void RejectPairing() = 0; 345 346 // Cancels a pairing or connection attempt to a remote device, releasing 347 // the pairing delegate. 348 virtual void CancelPairing() = 0; 349 350 // Disconnects the device, terminating the low-level ACL connection 351 // and any application connections using it. Link keys and other pairing 352 // information are not discarded, and the device object is not deleted. 353 // If the request fails, |error_callback| will be called; otherwise, 354 // |callback| is called when the request is complete. 355 virtual void Disconnect(const base::Closure& callback, 356 const ErrorCallback& error_callback) = 0; 357 358 // Disconnects the device, terminating the low-level ACL connection 359 // and any application connections using it, and then discards link keys 360 // and other pairing information. The device object remains valid until 361 // returning from the calling function, after which it should be assumed to 362 // have been deleted. If the request fails, |error_callback| will be called. 363 // There is no callback for success because this object is often deleted 364 // before that callback would be called. 365 virtual void Forget(const ErrorCallback& error_callback) = 0; 366 367 // Attempts to initiate an outgoing connection to this device for the profile 368 // identified by |profile|, on success the profile's connection callback 369 // will be called as well as |callback|; on failure |error_callback| will be 370 // called. 371 typedef base::Callback<void(const std::string&)> 372 ConnectToProfileErrorCallback; 373 virtual void ConnectToProfile( 374 BluetoothProfile* profile, 375 const base::Closure& callback, 376 const ConnectToProfileErrorCallback& error_callback) = 0; 377 378 // Attempts to initiate an outgoing L2CAP or RFCOMM connection to the 379 // advertised service on this device matching |uuid|, performing an SDP lookup 380 // if necessary to determine the correct protocol and channel for the 381 // connection. |callback| will be called on a successful connection with a 382 // BluetoothSocket instance that is to be owned by the receiver. 383 // |error_callback| will be called on failure with a message indicating the 384 // cause. 385 typedef base::Callback<void(scoped_refptr<BluetoothSocket>)> 386 ConnectToServiceCallback; 387 typedef base::Callback<void(const std::string& message)> 388 ConnectToServiceErrorCallback; 389 virtual void ConnectToService( 390 const BluetoothUUID& uuid, 391 const ConnectToServiceCallback& callback, 392 const ConnectToServiceErrorCallback& error_callback) = 0; 393 394 // Sets the Out Of Band pairing data for this device to |data|. Exactly one 395 // of |callback| or |error_callback| will be run. 396 virtual void SetOutOfBandPairingData( 397 const BluetoothOutOfBandPairingData& data, 398 const base::Closure& callback, 399 const ErrorCallback& error_callback) = 0; 400 401 // Clears the Out Of Band pairing data for this device. Exactly one of 402 // |callback| or |error_callback| will be run. 403 virtual void ClearOutOfBandPairingData( 404 const base::Closure& callback, 405 const ErrorCallback& error_callback) = 0; 406 407 // Returns the list of discovered GATT services. 408 virtual std::vector<BluetoothGattService*> GetGattServices() const; 409 410 // Returns the GATT service with device-specific identifier |identifier|. 411 // Returns NULL, if no such service exists. 412 virtual BluetoothGattService* GetGattService( 413 const std::string& identifier) const; 414 415 protected: 416 BluetoothDevice(); 417 418 // Returns the internal name of the Bluetooth device, used by GetName(). 419 virtual std::string GetDeviceName() const = 0; 420 421 // Mapping from the platform-specific GATT service identifiers to 422 // BluetoothGattService objects. 423 typedef std::map<std::string, BluetoothGattService*> GattServiceMap; 424 GattServiceMap gatt_services_; 425 426 private: 427 // Returns a localized string containing the device's bluetooth address and 428 // a device type for display when |name_| is empty. 429 base::string16 GetAddressWithLocalizedDeviceTypeName() const; 430}; 431 432} // namespace device 433 434#endif // DEVICE_BLUETOOTH_BLUETOOTH_DEVICE_H_ 435