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
5#ifndef CHROMEOS_DBUS_BLUETOOTH_DEVICE_CLIENT_H_
6#define CHROMEOS_DBUS_BLUETOOTH_DEVICE_CLIENT_H_
7
8#include <string>
9#include <vector>
10
11#include "base/callback.h"
12#include "base/observer_list.h"
13#include "base/values.h"
14#include "chromeos/chromeos_export.h"
15#include "chromeos/dbus/dbus_client.h"
16#include "dbus/object_path.h"
17#include "dbus/property.h"
18
19namespace chromeos {
20
21// BluetoothDeviceClient is used to communicate with objects representing
22// remote Bluetooth Devices.
23class CHROMEOS_EXPORT BluetoothDeviceClient : public DBusClient {
24 public:
25  // Structure of properties associated with bluetooth devices.
26  struct Properties : public dbus::PropertySet {
27    // The Bluetooth device address of the device. Read-only.
28    dbus::Property<std::string> address;
29
30    // The Bluetooth friendly name of the device. Read-only, to give a
31    // different local name, use the |alias| property.
32    dbus::Property<std::string> name;
33
34    // Proposed icon name for the device according to the freedesktop.org
35    // icon naming specification. Read-only.
36    dbus::Property<std::string> icon;
37
38    // The Bluetooth class of the device. Read-only.
39    dbus::Property<uint32> bluetooth_class;
40
41    // The GAP external appearance of the device. Read-only.
42    dbus::Property<uint16> appearance;
43
44    // Unique numeric identifier for the vendor of the device. Read-only.
45    dbus::Property<uint16> vendor;
46
47    // List of 128-bit UUIDs that represent the available remote services.
48    // Read-only.
49    dbus::Property<std::vector<std::string> > uuids;
50
51    // Indicates that the device is currently paired. Read-only.
52    dbus::Property<bool> paired;
53
54    // Indicates that the device is currently connected. Read-only.
55    dbus::Property<bool> connected;
56
57    // Whether the device is trusted, and connections should be always
58    // accepted and attempted when the device is visible.
59    dbus::Property<bool> trusted;
60
61    // Whether the device is blocked, connections will be always rejected
62    // and the device will not be visible.
63    dbus::Property<bool> blocked;
64
65    // Local alias for the device, if not set, is equal to |name|.
66    dbus::Property<std::string> alias;
67
68    // Object path of the adapter the device belongs to. Read-only.
69    dbus::Property<dbus::ObjectPath> adapter;
70
71    // Indicates whether the device is likely to only support pre-2.1
72    // PIN Code pairing rather than 2.1 Secure Simple Pairing, this can
73    // give false positives. Read-only.
74    dbus::Property<bool> legacy_pairing;
75
76    // Remote Device ID information in Linux kernel modalias format. Read-only.
77    dbus::Property<std::string> modalias;
78
79    // Received signal strength indicator that is set when the device is
80    // discovered during inquiry. Read-only.
81    dbus::Property<int16> rssi;
82
83    // Received signal strength indicator when a connection is open to the
84    // device. This property is not set unless connection monitor is enabled.
85    // Read-only.
86    dbus::Property<int16> connection_rssi;
87
88    // The transmit power level of the host when a connection is open
89    // to the device. This property is not set unless connection monitor is
90    // enabled. Read-only.
91    dbus::Property<int16> connection_tx_power;
92
93    // The maximum transmit power level of the host that can be set
94    // when connected to the device. Read-only.
95    dbus::Property<int16> connection_tx_power_max;
96
97    Properties(dbus::ObjectProxy* object_proxy,
98               const std::string& interface_name,
99               const PropertyChangedCallback& callback);
100    virtual ~Properties();
101  };
102
103  // Interface for observing changes from a remote bluetooth device.
104  class Observer {
105   public:
106    virtual ~Observer() {}
107
108    // Called when the remote device with object path |object_path| is added
109    // to the set of known devices.
110    virtual void DeviceAdded(const dbus::ObjectPath& object_path) {}
111
112    // Called when the remote device with object path |object_path| is removed
113    // from the set of known devices.
114    virtual void DeviceRemoved(const dbus::ObjectPath& object_path) {}
115
116    // Called when the device with object path |object_path| has a
117    // change in value of the property named |property_name|.
118    virtual void DevicePropertyChanged(const dbus::ObjectPath& object_path,
119                                       const std::string& property_name) {}
120  };
121
122  virtual ~BluetoothDeviceClient();
123
124  // Adds and removes observers for events on all remote bluetooth
125  // devices. Check the |object_path| parameter of observer methods to
126  // determine which device is issuing the event.
127  virtual void AddObserver(Observer* observer) = 0;
128  virtual void RemoveObserver(Observer* observer) = 0;
129
130  // Returns the list of device object paths associated with the given adapter
131  // identified by the D-Bus object path |adapter_path|.
132  virtual std::vector<dbus::ObjectPath> GetDevicesForAdapter(
133      const dbus::ObjectPath& adapter_path) = 0;
134
135  // Obtain the properties for the device with object path |object_path|,
136  // any values should be copied if needed.
137  virtual Properties* GetProperties(const dbus::ObjectPath& object_path) = 0;
138
139  // The ErrorCallback is used by device methods to indicate failure.
140  // It receives two arguments: the name of the error in |error_name| and
141  // an optional message in |error_message|.
142  typedef base::Callback<void(const std::string& error_name,
143                              const std::string& error_message)> ErrorCallback;
144
145  // Connects to the device with object path |object_path|, connecting any
146  // profiles that can be connected to and have been flagged as auto-connected;
147  // may be used to connect additional profiles for an already connected device,
148  // and succeeds if at least one profile is connected.
149  virtual void Connect(const dbus::ObjectPath& object_path,
150                       const base::Closure& callback,
151                       const ErrorCallback& error_callback) = 0;
152
153  // Disconnects the device with object path |object_path|, terminating
154  // the low-level ACL connection and any profiles using it.
155  virtual void Disconnect(const dbus::ObjectPath& object_path,
156                          const base::Closure& callback,
157                          const ErrorCallback& error_callback) = 0;
158
159  // Connects to the profile |uuid| on the device with object path
160  // |object_path|, provided that the profile has been registered with a
161  // handler on the local device.
162  virtual void ConnectProfile(const dbus::ObjectPath& object_path,
163                              const std::string& uuid,
164                              const base::Closure& callback,
165                              const ErrorCallback& error_callback) = 0;
166
167  // Disconnects from the profile |uuid| on the device with object path
168  // |object_path|.
169  virtual void DisconnectProfile(const dbus::ObjectPath& object_path,
170                                 const std::string& uuid,
171                                 const base::Closure& callback,
172                                 const ErrorCallback& error_callback) = 0;
173
174  // Initiates pairing with the device with object path |object_path| and
175  // retrieves all SDP records or GATT primary services. An agent must be
176  // registered to handle the pairing request.
177  virtual void Pair(const dbus::ObjectPath& object_path,
178                    const base::Closure& callback,
179                    const ErrorCallback& error_callback) = 0;
180
181  // Cancels an in-progress pairing with the device with object path
182  // |object_path| initiated by Pair().
183  virtual void CancelPairing(const dbus::ObjectPath& object_path,
184                             const base::Closure& callback,
185                             const ErrorCallback& error_callback) = 0;
186
187  // Starts connection monitor for the device with object path
188  // |object_path|. Connection monitor is a mode the connection properties,
189  // RSSI and TX power are tracked and updated when they change.
190  virtual void StartConnectionMonitor(const dbus::ObjectPath& object_path,
191                                      const base::Closure& callback,
192                                      const ErrorCallback& error_callback) = 0;
193
194  // Stops connection monitor for the device with object path
195  // |object_path|.
196  virtual void StopConnectionMonitor(const dbus::ObjectPath& object_path,
197                                     const base::Closure& callback,
198                                     const ErrorCallback& error_callback) = 0;
199
200  // Creates the instance.
201  static BluetoothDeviceClient* Create();
202
203  // Constants used to indicate exceptional error conditions.
204  static const char kNoResponseError[];
205  static const char kUnknownDeviceError[];
206
207 protected:
208  BluetoothDeviceClient();
209
210 private:
211  DISALLOW_COPY_AND_ASSIGN(BluetoothDeviceClient);
212};
213
214}  // namespace chromeos
215
216#endif  // CHROMEOS_DBUS_BLUETOOTH_DEVICE_CLIENT_H_
217