chromeos/dbus/bluetooth_device_client.h

   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
  19 namespace chromeos {
  20
  21 // BluetoothDeviceClient is used to communicate with objects representing
  22 // remote Bluetooth Devices.
  23 class 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_