bluetooth_gatt_interface.h revision a641b6fa2a25e1b5382945d13c4fa49d36084a78 
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 <mutex>
20#include <unordered_set>
21#include <vector>
22
23#include <base/macros.h>
24#include <hardware/bluetooth.h>
25#include <hardware/bt_gatt.h>
26
27namespace bluetooth {
28namespace hal {
29
30// This class represents the standard BT-GATT interface. This class combines
31// GATT profile server and client role operations with general GAP profile
32// operations of various roles (central, scanner, peripheral, advertiser),
33// wrapping around the underlying bt_gatt_interface_t structure. A single
34// instance of this class exists per application and it allows multiple classes
35// to interface with the global HAL interface by multiplexing callbacks among
36// registered clients.
37//
38// This is declared as an abstract interface so that a fake implementation can
39// be injected for testing the upper layer.
40class BluetoothGattInterface {
41 public:
42  // The standard BT-GATT client callback interface. The HAL interface doesn't
43  // allow registering "user data" that carries context beyond the callback
44  // parameters, forcing implementations to deal with global variables. The
45  // Observer interface is to redirect these events to interested parties in an
46  // object-oriented manner.
47  class ClientObserver {
48   public:
49    virtual ~ClientObserver() = default;
50
51    // All of the events below correspond to callbacks defined in
52    // "bt_gatt_client_callbacks_t" in the HAL API definitions.
53
54    virtual void RegisterClientCallback(
55        BluetoothGattInterface* gatt_iface,
56        int status, int client_if,
57        const bt_uuid_t& app_uuid);
58
59    virtual void ScanResultCallback(
60        BluetoothGattInterface* gatt_iface,
61        const bt_bdaddr_t& bda, int rssi,
62        vector<uint8_t> adv_data);
63
64    virtual void ConnectCallback(
65        BluetoothGattInterface* gatt_iface,
66        int conn_id,
67        int status,
68        int client_if,
69        const bt_bdaddr_t& bda);
70
71    virtual void DisconnectCallback(
72        BluetoothGattInterface* gatt_iface,
73        int conn_id,
74        int status,
75        int client_if,
76        const bt_bdaddr_t& bda);
77
78    virtual void SearchCompleteCallback(
79        BluetoothGattInterface* gatt_iface,
80        int conn_id,
81        int status);
82
83    virtual void RegisterForNotificationCallback(
84        BluetoothGattInterface* gatt_iface,
85        int conn_id, int status, int registered, uint16_t handle);
86
87    virtual void NotifyCallback(
88        BluetoothGattInterface* gatt_iface,
89        int conn_id, btgatt_notify_params_t* p_data);
90
91    virtual void WriteCharacteristicCallback(
92        BluetoothGattInterface* gatt_iface,
93        int conn_id, int status, uint16_t handle);
94
95    virtual void WriteDescriptorCallback(
96        BluetoothGattInterface* gatt_iface,
97        int conn_id, int status, uint16_t handle);
98
99    virtual void ListenCallback(
100        BluetoothGattInterface* gatt_iface,
101        int status, int client_if);
102
103    virtual void MtuChangedCallback(
104        BluetoothGattInterface* gatt_iface,
105        int conn_id, int status, int mtu);
106
107    virtual void MultiAdvEnableCallback(
108        BluetoothGattInterface* gatt_iface,
109        int client_if, int status);
110
111    virtual void MultiAdvUpdateCallback(
112        BluetoothGattInterface* gatt_iface,
113        int client_if, int status);
114
115    virtual void MultiAdvDataCallback(
116        BluetoothGattInterface* gatt_iface,
117        int client_if, int status);
118
119    virtual void MultiAdvDisableCallback(
120        BluetoothGattInterface* gatt_iface,
121        int client_if, int status);
122
123    virtual void GetGattDbCallback(
124        BluetoothGattInterface* gatt_iface,
125        int conn_id,
126        btgatt_db_element_t* gatt_db,
127        int size);
128
129    virtual void ServicesRemovedCallback(
130        BluetoothGattInterface* gatt_iface,
131        int conn_id,
132        uint16_t start_handle,
133        uint16_t end_handle);
134
135    virtual void ServicesAddedCallback(
136        BluetoothGattInterface* gatt_iface,
137        int conn_id,
138        btgatt_db_element_t *added,
139        int added_count);
140  };
141
142  // The standard BT-GATT server callback interface.
143  class ServerObserver {
144   public:
145    virtual ~ServerObserver() = default;
146
147    virtual void RegisterServerCallback(
148        BluetoothGattInterface* gatt_iface,
149        int status, int server_if,
150        const bt_uuid_t& app_uuid);
151
152    virtual void ConnectionCallback(
153        BluetoothGattInterface* gatt_iface,
154        int conn_id, int server_if,
155        int connected,
156        const bt_bdaddr_t& bda);
157
158    virtual void ServiceAddedCallback(
159        BluetoothGattInterface* gatt_iface,
160        int status, int server_if,
161        vector<btgatt_db_element_t> service);
162
163    virtual void ServiceStoppedCallback(
164        BluetoothGattInterface* gatt_iface,
165        int status, int server_if,
166        int srvc_handle);
167
168    virtual void ServiceDeletedCallback(
169        BluetoothGattInterface* gatt_iface,
170        int status, int server_if,
171        int srvc_handle);
172
173    virtual void RequestReadCharacteristicCallback(
174        BluetoothGattInterface* gatt_iface,
175        int conn_id, int trans_id,
176        const bt_bdaddr_t& bda,
177        int attr_handle, int offset,
178        bool is_long);
179
180    virtual void RequestReadDescriptorCallback(
181        BluetoothGattInterface* gatt_iface,
182        int conn_id, int trans_id,
183        const bt_bdaddr_t& bda,
184        int attr_handle, int offset,
185        bool is_long);
186
187    virtual void RequestWriteCharacteristicCallback(
188        BluetoothGattInterface* gatt_iface,
189        int conn_id, int trans_id,
190        const bt_bdaddr_t& bda,
191        int attr_handle, int offset,
192        bool need_rsp, bool is_prep,
193        vector<uint8_t> value);
194
195    virtual void RequestWriteDescriptorCallback(
196        BluetoothGattInterface* gatt_iface,
197        int conn_id, int trans_id,
198        const bt_bdaddr_t& bda,
199        int attr_handle, int offset,
200        bool need_rsp, bool is_prep,
201        vector<uint8_t> value);
202
203    virtual void RequestExecWriteCallback(
204        BluetoothGattInterface* gatt_iface,
205        int conn_id, int trans_id,
206        const bt_bdaddr_t& bda, int exec_write);
207
208    virtual void ResponseConfirmationCallback(
209        BluetoothGattInterface* gatt_iface,
210        int status,
211        int handle);
212
213    virtual void IndicationSentCallback(
214        BluetoothGattInterface* gatt_iface, int conn_id, int status);
215
216    virtual void MtuChangedCallback(
217        BluetoothGattInterface* gatt_iface, int conn_id, int mtu);
218  };
219
220  // Initialize and clean up the BluetoothInterface singleton. Returns false if
221  // the underlying HAL interface failed to initialize, and true on success.
222  static bool Initialize();
223
224  // Shuts down and cleans up the interface. CleanUp must be called on the same
225  // thread that called Initialize.
226  static void CleanUp();
227
228  // Returns true if the interface was initialized and a global singleton has
229  // been created.
230  static bool IsInitialized();
231
232  // Initialize for testing. Use this to inject a test version of
233  // BluetoothGattInterface. To be used from unit tests only.
234  static void InitializeForTesting(BluetoothGattInterface* test_instance);
235
236  // Returns the BluetoothGattInterface singleton. If the interface has
237  // not been initialized, returns nullptr. This method is thread-safe, in that
238  // it will block if the internal lock is being held by another thread. Don't
239  // call this re-entrantly from an observer event as this may cause a deadlock.
240  static BluetoothGattInterface* Get();
241
242  // Add or remove an observer that is interested in GATT client interface
243  // notifications from us. Thread-safety is guaranteed by ObserverList.
244  virtual void AddClientObserver(ClientObserver* observer) = 0;
245  virtual void RemoveClientObserver(ClientObserver* observer) = 0;
246
247  // Add or remove an observer that is interested in GATT server interface
248  // notifications from us. Thread-safety is guaranteed by ObserverList.
249  virtual void AddServerObserver(ServerObserver* observer) = 0;
250  virtual void RemoveServerObserver(ServerObserver* observer) = 0;
251
252  // The HAL module pointer that represents the standard BT-GATT client
253  // interface. This is implemented in and provided by the shared Bluetooth
254  // library, so this isn't owned by us.
255  //
256  // Upper layers can make btgatt_client_interface_t API calls through this
257  // structure.
258  virtual const btgatt_client_interface_t* GetClientHALInterface() const = 0;
259
260  // The HAL module pointer that represents the standard BT-GATT server
261  // interface. This is implemented in and provided by the shared Bluetooth
262  // library, so this isn't owned by us.
263  //
264  // Upper layers can make btgatt_server_interface_t API calls through this
265  // structure.
266  virtual const btgatt_server_interface_t* GetServerHALInterface() const = 0;
267
268  // Initiates a regular BLE device scan. This is called internally from each
269  // LowEnergyClient. This function synchronizes the scan requests and maintains
270  // an internal reference count for each scan client that is interested.
271  bt_status_t StartScan(int client_id);
272  bt_status_t StopScan(int client_id);
273
274 protected:
275  BluetoothGattInterface() = default;
276  virtual ~BluetoothGattInterface() = default;
277
278 private:
279  // Used to keep a reference count for the different BLE scan clients.
280  std::mutex scan_clients_lock_;
281  std::unordered_set<int> scan_client_set_;
282
283  DISALLOW_COPY_AND_ASSIGN(BluetoothGattInterface);
284};
285
286}  // namespace hal
287}  // namespace bluetooth
288