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 <string> 9 10 #include "base/callback.h" 11 #include "base/memory/ref_counted.h" 12 #include "base/memory/scoped_vector.h" 13 #include "base/strings/string16.h" 14 15 namespace device { 16 17 class BluetoothProfile; 18 class BluetoothServiceRecord; 19 class BluetoothSocket; 20 21 struct BluetoothOutOfBandPairingData; 22 23 // BluetoothDevice represents a remote Bluetooth device, both its properties and 24 // capabilities as discovered by a local adapter and actions that may be 25 // performed on the remove device such as pairing, connection and disconnection. 26 // 27 // The class is instantiated and managed by the BluetoothAdapter class 28 // and pointers should only be obtained from that class and not cached, 29 // instead use the GetAddress() method as a unique key for a device. 30 // 31 // Since the lifecycle of BluetoothDevice instances is managed by 32 // BluetoothAdapter, that class rather than this provides observer methods 33 // for devices coming and going, as well as properties being updated. 34 class BluetoothDevice { 35 public: 36 // Possible values that may be returned by GetDeviceType(), representing 37 // different types of bluetooth device that we support or are aware of 38 // decoded from the bluetooth class information. 39 enum DeviceType { 40 DEVICE_UNKNOWN, 41 DEVICE_COMPUTER, 42 DEVICE_PHONE, 43 DEVICE_MODEM, 44 DEVICE_AUDIO, 45 DEVICE_CAR_AUDIO, 46 DEVICE_VIDEO, 47 DEVICE_PERIPHERAL, 48 DEVICE_JOYSTICK, 49 DEVICE_GAMEPAD, 50 DEVICE_KEYBOARD, 51 DEVICE_MOUSE, 52 DEVICE_TABLET, 53 DEVICE_KEYBOARD_MOUSE_COMBO 54 }; 55 56 // Possible errors passed back to an error callback function in case of a 57 // failed call to Connect(). 58 enum ConnectErrorCode { 59 ERROR_UNKNOWN, 60 ERROR_INPROGRESS, 61 ERROR_FAILED, 62 ERROR_AUTH_FAILED, 63 ERROR_AUTH_CANCELED, 64 ERROR_AUTH_REJECTED, 65 ERROR_AUTH_TIMEOUT, 66 ERROR_UNSUPPORTED_DEVICE 67 }; 68 69 // Interface for observing changes from bluetooth devices. 70 class Observer { 71 public: ~Observer()72 virtual ~Observer() {} 73 74 // TODO(keybuk): add observers for pairing and connection. 75 }; 76 77 // Interface for negotiating pairing of bluetooth devices. 78 class PairingDelegate { 79 public: ~PairingDelegate()80 virtual ~PairingDelegate() {} 81 82 // This method will be called when the Bluetooth daemon requires a 83 // PIN Code for authentication of the device |device|, the delegate should 84 // obtain the code from the user and call SetPinCode() on the device to 85 // provide it, or RejectPairing() or CancelPairing() to reject or cancel 86 // the request. 87 // 88 // PIN Codes are generally required for Bluetooth 2.0 and earlier devices 89 // for which there is no automatic pairing or special handling. 90 virtual void RequestPinCode(BluetoothDevice* device) = 0; 91 92 // This method will be called when the Bluetooth daemon requires a 93 // Passkey for authentication of the device |device|, the delegate should 94 // obtain the passkey from the user (a numeric in the range 0-999999) and 95 // call SetPasskey() on the device to provide it, or RejectPairing() or 96 // CancelPairing() to reject or cancel the request. 97 // 98 // Passkeys are generally required for Bluetooth 2.1 and later devices 99 // which cannot provide input or display on their own, and don't accept 100 // passkey-less pairing. 101 virtual void RequestPasskey(BluetoothDevice* device) = 0; 102 103 // This method will be called when the Bluetooth daemon requires that the 104 // user enter the PIN code |pincode| into the device |device| so that it 105 // may be authenticated. The DismissDisplayOrConfirm() method 106 // will be called to dismiss the display once pairing is complete or 107 // cancelled. 108 // 109 // This is used for Bluetooth 2.0 and earlier keyboard devices, the 110 // |pincode| will always be a six-digit numeric in the range 000000-999999 111 // for compatibility with later specifications. 112 virtual void DisplayPinCode(BluetoothDevice* device, 113 const std::string& pincode) = 0; 114 115 // This method will be called when the Bluetooth daemon requires that the 116 // user enter the Passkey |passkey| into the device |device| so that it 117 // may be authenticated. The DismissDisplayOrConfirm() method will be 118 // called to dismiss the display once pairing is complete or cancelled. 119 // 120 // This is used for Bluetooth 2.1 and later devices that support input 121 // but not display, such as keyboards. The Passkey is a numeric in the 122 // range 0-999999 and should be always presented zero-padded to six 123 // digits. 124 virtual void DisplayPasskey(BluetoothDevice* device, 125 uint32 passkey) = 0; 126 127 // This method will be called when the Bluetooth daemon gets a notification 128 // of a key entered on the device |device| while pairing with the device 129 // using a PIN code or a Passkey. 130 // 131 // This method will be called only after DisplayPinCode() or 132 // DisplayPasskey() is called and before the corresponding 133 // DismissDisplayOrConfirm() is called, but is not warranted to be called 134 // on every pairing process that requires a PIN code or a Passkey because 135 // some device may not support this feature. 136 // 137 // The |entered| value describes the number of keys entered so far, 138 // including the last [enter] key. A first call to KeysEntered() with 139 // |entered| as 0 will be sent when the device supports this feature. 140 virtual void KeysEntered(BluetoothDevice* device, 141 uint32 entered) = 0; 142 143 // This method will be called when the Bluetooth daemon requires that the 144 // user confirm that the Passkey |passkey| is displayed on the screen 145 // of the device |device| so that it may be authenticated. The delegate 146 // should display to the user and ask for confirmation, then call 147 // ConfirmPairing() on the device to confirm, RejectPairing() on the device 148 // to reject or CancelPairing() on the device to cancel authentication 149 // for any other reason. 150 // 151 // This is used for Bluetooth 2.1 and later devices that support display, 152 // such as other computers or phones. The Passkey is a numeric in the 153 // range 0-999999 and should be always present zero-padded to six 154 // digits. 155 virtual void ConfirmPasskey(BluetoothDevice* device, 156 uint32 passkey) = 0; 157 158 // This method will be called when any previous DisplayPinCode(), 159 // DisplayPasskey() or ConfirmPasskey() request should be concluded 160 // and removed from the user. 161 virtual void DismissDisplayOrConfirm() = 0; 162 }; 163 164 // Returns true if uuid is in a a valid canonical format 165 // (see utils::CanonicalUuid). 166 static bool IsUUIDValid(const std::string& uuid); 167 168 virtual ~BluetoothDevice(); 169 170 // Returns the Bluetooth class of the device, used by GetDeviceType() 171 // and metrics logging, 172 virtual uint32 GetBluetoothClass() const = 0; 173 174 // Returns the Bluetooth of address the device. This should be used as 175 // a unique key to identify the device and copied where needed. 176 virtual std::string GetAddress() const = 0; 177 178 // Returns the Vendor ID of the device, where available. 179 virtual uint16 GetVendorID() const = 0; 180 181 // Returns the Product ID of the device, where available. 182 virtual uint16 GetProductID() const = 0; 183 184 // Returns the Device ID of the device, typically the release or version 185 // number in BCD format, where available. 186 virtual uint16 GetDeviceID() const = 0; 187 188 // Returns the name of the device suitable for displaying, this may 189 // be a synthesized string containing the address and localized type name 190 // if the device has no obtained name. 191 virtual string16 GetName() const; 192 193 // Returns the type of the device, limited to those we support or are 194 // aware of, by decoding the bluetooth class information. The returned 195 // values are unique, and do not overlap, so DEVICE_KEYBOARD is not also 196 // DEVICE_PERIPHERAL. 197 DeviceType GetDeviceType() const; 198 199 // Indicates whether the device is known to support pairing based on its 200 // device class and address. 201 bool IsPairable() const; 202 203 // Indicates whether the device is paired with the adapter. 204 virtual bool IsPaired() const = 0; 205 206 // Indicates whether the device is currently connected to the adapter. 207 // Note that if IsConnected() is true, does not imply that the device is 208 // connected to any application or service. If the device is not paired, it 209 // could be still connected to the adapter for other reason, for example, to 210 // request the adapter's SDP records. The same holds for paired devices, since 211 // they could be connected to the adapter but not to an application. 212 virtual bool IsConnected() const = 0; 213 214 // Indicates whether the paired device accepts connections initiated from the 215 // adapter. This value is undefined for unpaired devices. 216 virtual bool IsConnectable() const = 0; 217 218 // Indicates whether there is a call to Connect() ongoing. For this attribute, 219 // we consider a call is ongoing if none of the callbacks passed to Connect() 220 // were called after the corresponding call to Connect(). 221 virtual bool IsConnecting() const = 0; 222 223 // Returns the services (as UUID strings) that this device provides. 224 // TODO(youngki): Rename this to GetProfiles(). 225 typedef std::vector<std::string> ServiceList; 226 virtual ServiceList GetServices() const = 0; 227 228 // The ErrorCallback is used for methods that can fail in which case it 229 // is called, in the success case the callback is simply not called. 230 typedef base::Callback<void()> ErrorCallback; 231 232 // The ConnectErrorCallback is used for methods that can fail with an error, 233 // passed back as an error code argument to this callback. 234 // In the success case this callback is not called. 235 typedef base::Callback<void(enum ConnectErrorCode)> ConnectErrorCallback; 236 237 // Returns the services (as BluetoothServiceRecord objects) that this device 238 // provides. 239 typedef ScopedVector<BluetoothServiceRecord> ServiceRecordList; 240 typedef base::Callback<void(const ServiceRecordList&)> ServiceRecordsCallback; 241 virtual void GetServiceRecords(const ServiceRecordsCallback& callback, 242 const ErrorCallback& error_callback) = 0; 243 244 // Indicates whether this device provides the given service. 245 virtual bool ProvidesServiceWithUUID(const std::string& uuid) const; 246 247 // The ProvidesServiceCallback is used by ProvidesServiceWithName to indicate 248 // whether or not a matching service was found. 249 typedef base::Callback<void(bool)> ProvidesServiceCallback; 250 251 // Indicates whether this device provides the given service. 252 virtual void ProvidesServiceWithName( 253 const std::string& name, 254 const ProvidesServiceCallback& callback) = 0; 255 256 // Indicates whether the device is currently pairing and expecting a 257 // PIN Code to be returned. 258 virtual bool ExpectingPinCode() const = 0; 259 260 // Indicates whether the device is currently pairing and expecting a 261 // Passkey to be returned. 262 virtual bool ExpectingPasskey() const = 0; 263 264 // Indicates whether the device is currently pairing and expecting 265 // confirmation of a displayed passkey. 266 virtual bool ExpectingConfirmation() const = 0; 267 268 // SocketCallback is used by ConnectToService to return a BluetoothSocket to 269 // the caller, or NULL if there was an error. The socket will remain open 270 // until the last reference to the returned BluetoothSocket is released. 271 typedef base::Callback<void(scoped_refptr<BluetoothSocket>)> 272 SocketCallback; 273 274 // Initiates a connection to the device, pairing first if necessary. 275 // 276 // Method calls will be made on the supplied object |pairing_delegate| 277 // to indicate what display, and in response should make method calls 278 // back to the device object. Not all devices require user responses 279 // during pairing, so it is normal for |pairing_delegate| to receive no 280 // calls. To explicitly force a low-security connection without bonding, 281 // pass NULL, though this is ignored if the device is already paired. 282 // 283 // If the request fails, |error_callback| will be called; otherwise, 284 // |callback| is called when the request is complete. 285 // After calling Connect, CancelPairing should be called to cancel the pairing 286 // process and release |pairing_delegate_| if user cancels the pairing and 287 // closes the pairing UI. 288 virtual void Connect(PairingDelegate* pairing_delegate, 289 const base::Closure& callback, 290 const ConnectErrorCallback& error_callback) = 0; 291 292 // Sends the PIN code |pincode| to the remote device during pairing. 293 // 294 // PIN Codes are generally required for Bluetooth 2.0 and earlier devices 295 // for which there is no automatic pairing or special handling. 296 virtual void SetPinCode(const std::string& pincode) = 0; 297 298 // Sends the Passkey |passkey| to the remote device during pairing. 299 // 300 // Passkeys are generally required for Bluetooth 2.1 and later devices 301 // which cannot provide input or display on their own, and don't accept 302 // passkey-less pairing, and are a numeric in the range 0-999999. 303 virtual void SetPasskey(uint32 passkey) = 0; 304 305 // Confirms to the remote device during pairing that a passkey provided by 306 // the ConfirmPasskey() delegate call is displayed on both devices. 307 virtual void ConfirmPairing() = 0; 308 309 // Rejects a pairing or connection request from a remote device. 310 virtual void RejectPairing() = 0; 311 312 // Cancels a pairing or connection attempt to a remote device or release 313 // |pairing_deleage_| and |agent_|. 314 virtual void CancelPairing() = 0; 315 316 // Disconnects the device, terminating the low-level ACL connection 317 // and any application connections using it. Link keys and other pairing 318 // information are not discarded, and the device object is not deleted. 319 // If the request fails, |error_callback| will be called; otherwise, 320 // |callback| is called when the request is complete. 321 virtual void Disconnect(const base::Closure& callback, 322 const ErrorCallback& error_callback) = 0; 323 324 // Disconnects the device, terminating the low-level ACL connection 325 // and any application connections using it, and then discards link keys 326 // and other pairing information. The device object remains valid until 327 // returning from the calling function, after which it should be assumed to 328 // have been deleted. If the request fails, |error_callback| will be called. 329 // There is no callback for success because this object is often deleted 330 // before that callback would be called. 331 virtual void Forget(const ErrorCallback& error_callback) = 0; 332 333 // Attempts to open a socket to a service matching |uuid| on this device. If 334 // the connection is successful, |callback| is called with a BluetoothSocket. 335 // Otherwise |callback| is called with NULL. The socket is closed as soon as 336 // all references to the BluetoothSocket are released. Note that the 337 // BluetoothSocket object can outlive both this BluetoothDevice and the 338 // BluetoothAdapter for this device. 339 virtual void ConnectToService(const std::string& service_uuid, 340 const SocketCallback& callback) = 0; 341 342 // Attempts to initiate an outgoing connection to this device for the profile 343 // identified by |profile|, on success the profile's connection callback 344 // will be called as well as |callback|; on failure |error_callback| will be 345 // called. 346 virtual void ConnectToProfile(BluetoothProfile* profile, 347 const base::Closure& callback, 348 const ErrorCallback& error_callback) = 0; 349 350 // Sets the Out Of Band pairing data for this device to |data|. Exactly one 351 // of |callback| or |error_callback| will be run. 352 virtual void SetOutOfBandPairingData( 353 const BluetoothOutOfBandPairingData& data, 354 const base::Closure& callback, 355 const ErrorCallback& error_callback) = 0; 356 357 // Clears the Out Of Band pairing data for this device. Exactly one of 358 // |callback| or |error_callback| will be run. 359 virtual void ClearOutOfBandPairingData( 360 const base::Closure& callback, 361 const ErrorCallback& error_callback) = 0; 362 363 protected: 364 BluetoothDevice(); 365 366 // Returns the internal name of the Bluetooth device, used by GetName(). 367 virtual std::string GetDeviceName() const = 0; 368 369 private: 370 // Returns a localized string containing the device's bluetooth address and 371 // a device type for display when |name_| is empty. 372 string16 GetAddressWithLocalizedDeviceTypeName() const; 373 }; 374 375 } // namespace device 376 377 #endif // DEVICE_BLUETOOTH_BLUETOOTH_DEVICE_H_ 378