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
15namespace device {
16
17class BluetoothDevice;
18
19struct 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.
27class 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_
171