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.
5 #ifndef DEVICE_BLUETOOTH_BLUETOOTH_DEVICE_H_
6 #define DEVICE_BLUETOOTH_BLUETOOTH_DEVICE_H_
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"
17 class BluetoothProfile;
18 class BluetoothServiceRecord;
19 class BluetoothSocket;
21 struct BluetoothOutOfBandPairingData;
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.
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.
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 {
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.
53 DEVICE_KEYBOARD_MOUSE_COMBO
56 // Possible errors passed back to an error callback function in case of a
57 // failed call to Connect().
58 enum ConnectErrorCode {
66 ERROR_UNSUPPORTED_DEVICE
69 // Interface for observing changes from bluetooth devices.
72 virtual ~Observer() {}
74 // TODO(keybuk): add observers for pairing and connection.
77 // Interface for negotiating pairing of bluetooth devices.
78 class PairingDelegate {
80 virtual ~PairingDelegate() {}
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
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;
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.
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;
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
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;
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.
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
124 virtual void DisplayPasskey(BluetoothDevice* device,
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.
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.
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,
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.
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
155 virtual void ConfirmPasskey(BluetoothDevice* device,
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;
164 // Returns true if uuid is in a a valid canonical format
165 // (see utils::CanonicalUuid).
166 static bool IsUUIDValid(const std::string& uuid);
168 virtual ~BluetoothDevice();
170 // Returns the Bluetooth class of the device, used by GetDeviceType()
171 // and metrics logging,
172 virtual uint32 GetBluetoothClass() const = 0;
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;
178 // Returns the Vendor ID of the device, where available.
179 virtual uint16 GetVendorID() const = 0;
181 // Returns the Product ID of the device, where available.
182 virtual uint16 GetProductID() const = 0;
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;
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;
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;
199 // Indicates whether the device is known to support pairing based on its
200 // device class and address.
201 bool IsPairable() const;
203 // Indicates whether the device is paired with the adapter.
204 virtual bool IsPaired() const = 0;
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;
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;
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;
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;
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;
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;
237 // Returns the services (as BluetoothServiceRecord objects) that this device
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;
244 // Indicates whether this device provides the given service.
245 virtual bool ProvidesServiceWithUUID(const std::string& uuid) const;
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;
251 // Indicates whether this device provides the given service.
252 virtual void ProvidesServiceWithName(
253 const std::string& name,
254 const ProvidesServiceCallback& callback) = 0;
256 // Indicates whether the device is currently pairing and expecting a
257 // PIN Code to be returned.
258 virtual bool ExpectingPinCode() const = 0;
260 // Indicates whether the device is currently pairing and expecting a
261 // Passkey to be returned.
262 virtual bool ExpectingPasskey() const = 0;
264 // Indicates whether the device is currently pairing and expecting
265 // confirmation of a displayed passkey.
266 virtual bool ExpectingConfirmation() const = 0;
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>)>
274 // Initiates a connection to the device, pairing first if necessary.
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.
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;
292 // Sends the PIN code |pincode| to the remote device during pairing.
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;
298 // Sends the Passkey |passkey| to the remote device during pairing.
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;
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;
309 // Rejects a pairing or connection request from a remote device.
310 virtual void RejectPairing() = 0;
312 // Cancels a pairing or connection attempt to a remote device or release
313 // |pairing_deleage_| and |agent_|.
314 virtual void CancelPairing() = 0;
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;
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;
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;
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
346 virtual void ConnectToProfile(BluetoothProfile* profile,
347 const base::Closure& callback,
348 const ErrorCallback& error_callback) = 0;
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;
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;
366 // Returns the internal name of the Bluetooth device, used by GetName().
367 virtual std::string GetDeviceName() const = 0;
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;
375 } // namespace device
377 #endif // DEVICE_BLUETOOTH_BLUETOOTH_DEVICE_H_