low_energy_client.h revision 08f80ebd5c714364cb76cc4e4a93454b42ed5669 
1//
2//  Copyright (C) 2015 Google, Inc.
3//
4//  Licensed under the Apache License, Version 2.0 (the "License");
5//  you may not use this file except in compliance with the License.
6//  You may obtain a copy of the License at:
7//
8//  http://www.apache.org/licenses/LICENSE-2.0
9//
10//  Unless required by applicable law or agreed to in writing, software
11//  distributed under the License is distributed on an "AS IS" BASIS,
12//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13//  See the License for the specific language governing permissions and
14//  limitations under the License.
15//
16
17#pragma once
18
19#include <atomic>
20#include <functional>
21#include <map>
22#include <mutex>
23
24#include <base/macros.h>
25
26#include "service/advertise_data.h"
27#include "service/advertise_settings.h"
28#include "service/bluetooth_client_instance.h"
29#include "service/hal/bluetooth_gatt_interface.h"
30#include "service/low_energy_constants.h"
31#include "service/uuid.h"
32
33namespace bluetooth {
34
35// A LowEnergyClient represents an application's handle to perform various
36// Bluetooth Low Energy GAP operations. Instances cannot be created directly and
37// should be obtained through the factory.
38class LowEnergyClient : private hal::BluetoothGattInterface::ClientObserver,
39                        public BluetoothClientInstance {
40 public:
41  // The destructor automatically unregisters this client instance from the
42  // stack.
43  ~LowEnergyClient() override;
44
45  // Callback type used to return the result of asynchronous operations below.
46  using StatusCallback = std::function<void(BLEStatus)>;
47
48  // Starts advertising based on the given advertising and scan response
49  // data and the provided |settings|. Reports the result of the operation in
50  // |callback|.
51  bool StartAdvertising(const AdvertiseSettings& settings,
52                        const AdvertiseData& advertise_data,
53                        const AdvertiseData& scan_response,
54                        const StatusCallback& callback);
55
56  // Stops advertising if it was already started. Reports the result of the
57  // operation in |callback|.
58  bool StopAdvertising(const StatusCallback& callback);
59
60  // Returns true if advertising has been started.
61  bool IsAdvertisingStarted() const;
62
63  // Returns the state of pending advertising operations.
64  bool IsStartingAdvertising() const;
65  bool IsStoppingAdvertising() const;
66
67  // Returns the current advertising settings.
68  const AdvertiseSettings& settings() const { return settings_; }
69
70  // BluetoothClientInstace overrides:
71  const UUID& GetAppIdentifier() const override;
72  int GetClientId() const override;
73
74 private:
75  friend class LowEnergyClientFactory;
76
77  // Constructor shouldn't be called directly as instances are meant to be
78  // obtained from the factory.
79  LowEnergyClient(const UUID& uuid, int client_if);
80
81  // BluetoothGattInterface::ClientObserver overrides:
82  void MultiAdvEnableCallback(
83      hal::BluetoothGattInterface* gatt_iface,
84      int client_if, int status) override;
85  void MultiAdvDataCallback(
86      hal::BluetoothGattInterface* gatt_iface,
87      int client_if, int status) override;
88  void MultiAdvDisableCallback(
89      hal::BluetoothGattInterface* gatt_iface,
90      int client_if, int status) override;
91
92  // Helper method called from SetAdvertiseData/SetScanResponse.
93  bt_status_t SetAdvertiseData(
94      hal::BluetoothGattInterface* gatt_iface,
95      const AdvertiseData& data,
96      bool set_scan_rsp);
97
98  // Handles deferred advertise/scan-response data updates. We set the data if
99  // there's data to be set, otherwise we either defer it if advertisements
100  // aren't enabled or do nothing.
101  void HandleDeferredAdvertiseData(hal::BluetoothGattInterface* gatt_iface);
102
103  // Calls and clears the pending callbacks.
104  void InvokeAndClearStartCallback(BLEStatus status);
105  void InvokeAndClearStopCallback(BLEStatus status);
106
107  // See getters above for documentation.
108  UUID app_identifier_;
109  int client_if_;
110
111  // Protects advertising-related members below.
112  std::mutex adv_fields_lock_;
113
114  // The advertising and scan response data fields that will be sent to the
115  // controller.
116  AdvertiseData adv_data_;
117  AdvertiseData scan_response_;
118  std::atomic_bool adv_data_needs_update_;
119  std::atomic_bool scan_rsp_needs_update_;
120
121  // Latest advertising settings.
122  AdvertiseSettings settings_;
123
124  // Whether or not there is a pending call to update advertising or scan
125  // response data.
126  std::atomic_bool is_setting_adv_data_;
127
128  std::atomic_bool adv_started_;
129  std::unique_ptr<StatusCallback> adv_start_callback_;
130  std::unique_ptr<StatusCallback> adv_stop_callback_;
131
132  DISALLOW_COPY_AND_ASSIGN(LowEnergyClient);
133};
134
135// LowEnergyClientFactory is used to register and obtain a per-application
136// LowEnergyClient instance. Users should call RegisterClient to obtain their
137// own unique LowEnergyClient instance that has been registered with the
138// Bluetooth stack.
139class LowEnergyClientFactory
140    : private hal::BluetoothGattInterface::ClientObserver,
141      public BluetoothClientInstanceFactory {
142 public:
143  // Don't construct/destruct directly except in tests. Instead, obtain a handle
144  // from an Adapter instance.
145  LowEnergyClientFactory();
146  ~LowEnergyClientFactory() override;
147
148  // BluetoothClientInstanceFactory override:
149  bool RegisterClient(const UUID& uuid,
150                      const RegisterCallback& callback) override;
151
152 private:
153  // BluetoothGattInterface::ClientObserver overrides:
154  void RegisterClientCallback(
155      hal::BluetoothGattInterface* gatt_iface,
156      int status, int client_if,
157      const bt_uuid_t& app_uuid) override;
158
159  // Map of pending calls to register.
160  std::mutex pending_calls_lock_;
161  std::map<UUID, RegisterCallback> pending_calls_;
162
163  DISALLOW_COPY_AND_ASSIGN(LowEnergyClientFactory);
164};
165
166}  // namespace bluetooth
167