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 <string>
   9 #include <vector>
  10
  11 #include "base/callback.h"
  12 #include "base/memory/ref_counted.h"
  13
  14 namespace device {
  15
  16 class BluetoothDevice;
  17
  18 struct BluetoothOutOfBandPairingData;
  19
  20 // BluetoothAdapter represents a local Bluetooth adapter which may be used to
  21 // interact with remote Bluetooth devices. As well as providing support for
  22 // determining whether an adapter is present, and whether the radio is powered,
  23 // this class also provides support for obtaining the list of remote devices
  24 // known to the adapter, discovering new devices, and providing notification of
  25 // updates to device information.
  26 class BluetoothAdapter : public base::RefCounted<BluetoothAdapter> {
  27  public:
  28   // Interface for observing changes from bluetooth adapters.
  29   class Observer {
  30    public:
  31     virtual ~Observer() {}
  32
  33     // Called when the presence of the adapter |adapter| changes, when
  34     // |present| is true the adapter is now present, false means the adapter
  35     // has been removed from the system.
  36     virtual void AdapterPresentChanged(BluetoothAdapter* adapter,
  37                                        bool present) {}
  38
  39     // Called when the radio power state of the adapter |adapter| changes,
  40     // when |powered| is true the adapter radio is powered, false means the
  41     // adapter radio is off.
  42     virtual void AdapterPoweredChanged(BluetoothAdapter* adapter,
  43                                        bool powered) {}
  44
  45     // Called when the discovering state of the adapter |adapter| changes,
  46     // when |discovering| is true the adapter is seeking new devices, false
  47     // means it is not. Note that device discovery involves both states when
  48     // the adapter is seeking new devices and states when it is not because
  49     // it is interrogating the devices it found.
  50     virtual void AdapterDiscoveringChanged(BluetoothAdapter* adapter,
  51                                            bool discovering) {}
  52
  53     // Called when a new device |device| is added to the adapter |adapter|,
  54     // either because it has been discovered or a connection made. |device|
  55     // should not be cached, instead copy its address.
  56     virtual void DeviceAdded(BluetoothAdapter* adapter,
  57                              BluetoothDevice* device) {}
  58
  59     // Called when properties of the device |device| known to the adapter
  60     // |adapter| change. |device| should not be cached, instead copy its
  61     // address.
  62     virtual void DeviceChanged(BluetoothAdapter* adapter,
  63                                BluetoothDevice* device) {}
  64
  65     // Called when the device |device| is removed from the adapter |adapter|,
  66     // either as a result of a discovered device being lost between discovering
  67     // phases or pairing information deleted. |device| should not be cached.
  68     virtual void DeviceRemoved(BluetoothAdapter* adapter,
  69                                BluetoothDevice* device) {}
  70   };
  71
  72   // The ErrorCallback is used for methods that can fail in which case it
  73   // is called, in the success case the callback is simply not called.
  74   typedef base::Callback<void()> ErrorCallback;
  75
  76   // The BluetoothOutOfBandPairingDataCallback is used to return
  77   // BluetoothOutOfBandPairingData to the caller.
  78   typedef base::Callback<void(const BluetoothOutOfBandPairingData& data)>
  79       BluetoothOutOfBandPairingDataCallback;
  80
  81   // Adds and removes observers for events on this bluetooth adapter,
  82   // if monitoring multiple adapters check the |adapter| parameter of
  83   // observer methods to determine which adapter is issuing the event.
  84   virtual void AddObserver(BluetoothAdapter::Observer* observer) = 0;
  85   virtual void RemoveObserver(
  86       BluetoothAdapter::Observer* observer) = 0;
  87
  88   // The address of this adapter.  The address format is "XX:XX:XX:XX:XX:XX",
  89   // where each XX is a hexadecimal number.
  90   virtual const std::string& address() const;
  91
  92   // The name of the adapter.
  93   virtual const std::string& name() const;
  94
  95   // Indicates whether the adapter is actually present on the system, for
  96   // the default adapter this indicates whether any adapter is present. An
  97   // adapter is only considered present if the address has been obtained.
  98   virtual bool IsPresent() const = 0;
  99
 100   // Indicates whether the adapter radio is powered.
 101   virtual bool IsPowered() const = 0;
 102
 103   // Requests a change to the adapter radio power, setting |powered| to true
 104   // will turn on the radio and false will turn it off.  On success, callback
 105   // will be called.  On failure, |error_callback| will be called.
 106   virtual void SetPowered(bool powered,
 107                           const base::Closure& callback,
 108                           const ErrorCallback& error_callback) = 0;
 109
 110   // Indicates whether the adapter is currently discovering new devices,
 111   // note that a typical discovery process has phases of this being true
 112   // followed by phases of being false when the adapter interrogates the
 113   // devices found.
 114   virtual bool IsDiscovering() const = 0;
 115
 116   // Requests that the adapter either begin discovering new devices when
 117   // |discovering| is true, or cease any discovery when false.  On success,
 118   // callback will be called.  On failure, |error_callback| will be called.
 119   virtual void SetDiscovering(bool discovering,
 120                               const base::Closure& callback,
 121                               const ErrorCallback& error_callback) = 0;
 122
 123   // Requests the list of devices from the adapter, all are returned
 124   // including those currently connected and those paired. Use the
 125   // returned device pointers to determine which they are.
 126   typedef std::vector<BluetoothDevice*> DeviceList;
 127   virtual DeviceList GetDevices();
 128   typedef std::vector<const BluetoothDevice*> ConstDeviceList;
 129   virtual ConstDeviceList GetDevices() const = 0;
 130
 131   // Returns a pointer to the device with the given address |address| or
 132   // NULL if no such device is known.
 133   virtual BluetoothDevice* GetDevice(const std::string& address) = 0;
 134   virtual const BluetoothDevice* GetDevice(
 135       const std::string& address) const = 0;
 136
 137   // Requests the local Out Of Band pairing data.
 138   virtual void ReadLocalOutOfBandPairingData(
 139       const BluetoothOutOfBandPairingDataCallback& callback,
 140       const ErrorCallback& error_callback) = 0;
 141
 142  protected:
 143   friend class base::RefCounted<BluetoothAdapter>;
 144   virtual ~BluetoothAdapter();
 145
 146   // Address of the adapter.
 147   std::string address_;
 148
 149   // Name of the adapter.
 150   std::string name_;
 151 };
 152
 153 }  // namespace device
 154
 155 #endif  // DEVICE_BLUETOOTH_BLUETOOTH_ADAPTER_H_