src/device/bluetooth/bluetooth_adapter.h

   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_ADAPTER_H_
   6 #define DEVICE_BLUETOOTH_BLUETOOTH_ADAPTER_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
  15 namespace device {
  16
  17 class BluetoothDevice;
  18
  19 struct BluetoothOutOfBandPairingData;
  20
  21 // BluetoothAdapter represents a local Bluetooth adapter which may be used to
  22 // interact with remote Bluetooth devices. As well as providing support for
  23 // determining whether an adapter is present, and whether the radio is powered,
  24 // this class also provides support for obtaining the list of remote devices
  25 // known to the adapter, discovering new devices, and providing notification of
  26 // updates to device information.
  27 class BluetoothAdapter : public base::RefCounted<BluetoothAdapter> {
  28  public:
  29   // Interface for observing changes from bluetooth adapters.
  30   class Observer {
  31    public:
  32     virtual ~Observer() {}
  33
  34     // Called when the presence of the adapter |adapter| changes, when
  35     // |present| is true the adapter is now present, false means the adapter
  36     // has been removed from the system.
  37     virtual void AdapterPresentChanged(BluetoothAdapter* adapter,
  38                                        bool present) {}
  39
  40     // Called when the radio power state of the adapter |adapter| changes,
  41     // when |powered| is true the adapter radio is powered, false means the
  42     // adapter radio is off.
  43     virtual void AdapterPoweredChanged(BluetoothAdapter* adapter,
  44                                        bool powered) {}
  45
  46     // Called when the discovering state of the adapter |adapter| changes,
  47     // when |discovering| is true the adapter is seeking new devices, false
  48     // means it is not.
  49     virtual void AdapterDiscoveringChanged(BluetoothAdapter* adapter,
  50                                            bool discovering) {}
  51
  52     // Called when a new device |device| is added to the adapter |adapter|,
  53     // either because it has been discovered or a connection made. |device|
  54     // should not be cached, instead copy its address.
  55     virtual void DeviceAdded(BluetoothAdapter* adapter,
  56                              BluetoothDevice* device) {}
  57
  58     // Called when properties of the device |device| known to the adapter
  59     // |adapter| change. |device| should not be cached, instead copy its
  60     // address.
  61     virtual void DeviceChanged(BluetoothAdapter* adapter,
  62                                BluetoothDevice* device) {}
  63
  64     // Called when the device |device| is removed from the adapter |adapter|,
  65     // either as a result of a discovered device being lost between discovering
  66     // phases or pairing information deleted. |device| should not be cached.
  67     virtual void DeviceRemoved(BluetoothAdapter* adapter,
  68                                BluetoothDevice* device) {}
  69   };
  70
  71   // The ErrorCallback is used for methods that can fail in which case it
  72   // is called, in the success case the callback is simply not called.
  73   typedef base::Callback<void()> ErrorCallback;
  74
  75   // The BluetoothOutOfBandPairingDataCallback is used to return
  76   // BluetoothOutOfBandPairingData to the caller.
  77   typedef base::Callback<void(const BluetoothOutOfBandPairingData& data)>
  78       BluetoothOutOfBandPairingDataCallback;
  79
  80   // Adds and removes observers for events on this bluetooth adapter,
  81   // if monitoring multiple adapters check the |adapter| parameter of
  82   // observer methods to determine which adapter is issuing the event.
  83   virtual void AddObserver(BluetoothAdapter::Observer* observer) = 0;
  84   virtual void RemoveObserver(
  85       BluetoothAdapter::Observer* observer) = 0;
  86
  87   // The address of this adapter.  The address format is "XX:XX:XX:XX:XX:XX",
  88   // where each XX is a hexadecimal number.
  89   virtual std::string GetAddress() const = 0;
  90
  91   // The name of the adapter.
  92   virtual std::string GetName() const = 0;
  93
  94   // Indicates whether the adapter is initialized and ready to use.
  95   virtual bool IsInitialized() const = 0;
  96
  97   // Indicates whether the adapter is actually present on the system, for
  98   // the default adapter this indicates whether any adapter is present. An
  99   // adapter is only considered present if the address has been obtained.
 100   virtual bool IsPresent() const = 0;
 101
 102   // Indicates whether the adapter radio is powered.
 103   virtual bool IsPowered() const = 0;
 104
 105   // Requests a change to the adapter radio power, setting |powered| to true
 106   // will turn on the radio and false will turn it off.  On success, callback
 107   // will be called.  On failure, |error_callback| will be called.
 108   virtual void SetPowered(bool powered,
 109                           const base::Closure& callback,
 110                           const ErrorCallback& error_callback) = 0;
 111
 112   // Indicates whether the adapter is currently discovering new devices.
 113   virtual bool IsDiscovering() const = 0;
 114
 115   // Requests that the adapter begin discovering new devices, code must
 116   // always call this method if they require the adapter be in discovery
 117   // and should not make it conditional on the value of IsDiscovering()
 118   // as other adapter users may be making the same request. Code must also
 119   // call StopDiscovering() when done. On success |callback| will be called,
 120   // on failure |error_callback| will be called instead.
 121   //
 122   // Since discovery may already be in progress when this method is called,
 123   // callers should retrieve the current set of discovered devices by calling
 124   // GetDevices() and checking for those with IsPaired() as false.
 125   virtual void StartDiscovering(const base::Closure& callback,
 126                                 const ErrorCallback& error_callback) = 0;
 127
 128   // Requests that an earlier call to StartDiscovering() be cancelled; the
 129   // adapter may not actually cease discovering devices if other callers
 130   // have called StartDiscovering() and not yet called this method. On
 131   // success |callback| will be called, on failure |error_callback| will be
 132   // called instead.
 133   virtual void StopDiscovering(const base::Closure& callback,
 134                                const ErrorCallback& error_callback) = 0;
 135
 136   // Requests the list of devices from the adapter, all are returned
 137   // including those currently connected and those paired. Use the
 138   // returned device pointers to determine which they are.
 139   typedef std::vector<BluetoothDevice*> DeviceList;
 140   virtual DeviceList GetDevices();
 141   typedef std::vector<const BluetoothDevice*> ConstDeviceList;
 142   virtual ConstDeviceList GetDevices() const;
 143
 144   // Returns a pointer to the device with the given address |address| or
 145   // NULL if no such device is known.
 146   virtual BluetoothDevice* GetDevice(const std::string& address);
 147   virtual const BluetoothDevice* GetDevice(
 148       const std::string& address) const;
 149
 150   // Requests the local Out Of Band pairing data.
 151   virtual void ReadLocalOutOfBandPairingData(
 152       const BluetoothOutOfBandPairingDataCallback& callback,
 153       const ErrorCallback& error_callback) = 0;
 154
 155  protected:
 156   friend class base::RefCounted<BluetoothAdapter>;
 157   BluetoothAdapter();
 158   virtual ~BluetoothAdapter();
 159
 160   // Devices paired with, connected to, discovered by, or visible to the
 161   // adapter. The key is the Bluetooth address of the device and the value
 162   // is the BluetoothDevice object whose lifetime is managed by the
 163   // adapter instance.
 164   typedef std::map<const std::string, BluetoothDevice*> DevicesMap;
 165   DevicesMap devices_;
 166 };
 167
 168 }  // namespace device
 169
 170 #endif  // DEVICE_BLUETOOTH_BLUETOOTH_ADAPTER_H_