service/hal/bluetooth_gatt_interface.h

   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
  27 namespace bluetooth {
  28 namespace 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.
  40 class 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         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         const btgatt_srvc_id_t& srvc_id,
 162         int srvc_handle);
 163
 164     virtual void CharacteristicAddedCallback(
 165         BluetoothGattInterface* gatt_iface,
 166         int status, int server_if,
 167         const bt_uuid_t& uuid,
 168         int srvc_handle,
 169         int char_handle);
 170
 171     virtual void DescriptorAddedCallback(
 172         BluetoothGattInterface* gatt_iface,
 173         int status, int server_if,
 174         const bt_uuid_t& uuid,
 175         int srvc_handle,
 176         int desc_handle);
 177
 178     virtual void ServiceStartedCallback(
 179         BluetoothGattInterface* gatt_iface,
 180         int status, int server_if,
 181         int srvc_handle);
 182
 183     virtual void ServiceStoppedCallback(
 184         BluetoothGattInterface* gatt_iface,
 185         int status, int server_if,
 186         int srvc_handle);
 187
 188     virtual void ServiceDeletedCallback(
 189         BluetoothGattInterface* gatt_iface,
 190         int status, int server_if,
 191         int srvc_handle);
 192
 193     virtual void RequestReadCallback(
 194         BluetoothGattInterface* gatt_iface,
 195         int conn_id, int trans_id,
 196         const bt_bdaddr_t& bda,
 197         int attr_handle, int offset,
 198         bool is_long);
 199
 200     virtual void RequestWriteCallback(
 201         BluetoothGattInterface* gatt_iface,
 202         int conn_id, int trans_id,
 203         const bt_bdaddr_t& bda,
 204         int attr_handle, int offset, int length,
 205         bool need_rsp, bool is_prep, uint8_t* value);
 206
 207     virtual void RequestExecWriteCallback(
 208         BluetoothGattInterface* gatt_iface,
 209         int conn_id, int trans_id,
 210         const bt_bdaddr_t& bda, int exec_write);
 211
 212     virtual void ResponseConfirmationCallback(
 213         BluetoothGattInterface* gatt_iface,
 214         int status,
 215         int handle);
 216
 217     virtual void IndicationSentCallback(
 218         BluetoothGattInterface* gatt_iface, int conn_id, int status);
 219
 220     virtual void MtuChangedCallback(
 221         BluetoothGattInterface* gatt_iface, int conn_id, int mtu);
 222   };
 223
 224   // Initialize and clean up the BluetoothInterface singleton. Returns false if
 225   // the underlying HAL interface failed to initialize, and true on success.
 226   static bool Initialize();
 227
 228   // Shuts down and cleans up the interface. CleanUp must be called on the same
 229   // thread that called Initialize.
 230   static void CleanUp();
 231
 232   // Returns true if the interface was initialized and a global singleton has
 233   // been created.
 234   static bool IsInitialized();
 235
 236   // Initialize for testing. Use this to inject a test version of
 237   // BluetoothGattInterface. To be used from unit tests only.
 238   static void InitializeForTesting(BluetoothGattInterface* test_instance);
 239
 240   // Returns the BluetoothGattInterface singleton. If the interface has
 241   // not been initialized, returns nullptr. This method is thread-safe, in that
 242   // it will block if the internal lock is being held by another thread. Don't
 243   // call this re-entrantly from an observer event as this may cause a deadlock.
 244   static BluetoothGattInterface* Get();
 245
 246   // Add or remove an observer that is interested in GATT client interface
 247   // notifications from us. Thread-safety is guaranteed by ObserverList.
 248   virtual void AddClientObserver(ClientObserver* observer) = 0;
 249   virtual void RemoveClientObserver(ClientObserver* observer) = 0;
 250
 251   // Add or remove an observer that is interested in GATT server interface
 252   // notifications from us. Thread-safety is guaranteed by ObserverList.
 253   virtual void AddServerObserver(ServerObserver* observer) = 0;
 254   virtual void RemoveServerObserver(ServerObserver* observer) = 0;
 255
 256   // The HAL module pointer that represents the standard BT-GATT client
 257   // interface. This is implemented in and provided by the shared Bluetooth
 258   // library, so this isn't owned by us.
 259   //
 260   // Upper layers can make btgatt_client_interface_t API calls through this
 261   // structure.
 262   virtual const btgatt_client_interface_t* GetClientHALInterface() const = 0;
 263
 264   // The HAL module pointer that represents the standard BT-GATT server
 265   // interface. This is implemented in and provided by the shared Bluetooth
 266   // library, so this isn't owned by us.
 267   //
 268   // Upper layers can make btgatt_server_interface_t API calls through this
 269   // structure.
 270   virtual const btgatt_server_interface_t* GetServerHALInterface() const = 0;
 271
 272   // Initiates a regular BLE device scan. This is called internally from each
 273   // LowEnergyClient. This function synchronizes the scan requests and maintains
 274   // an internal reference count for each scan client that is interested.
 275   bt_status_t StartScan(int client_id);
 276   bt_status_t StopScan(int client_id);
 277
 278  protected:
 279   BluetoothGattInterface() = default;
 280   virtual ~BluetoothGattInterface() = default;
 281
 282  private:
 283   // Used to keep a reference count for the different BLE scan clients.
 284   std::mutex scan_clients_lock_;
 285   std::unordered_set<int> scan_client_set_;
 286
 287   DISALLOW_COPY_AND_ASSIGN(BluetoothGattInterface);
 288 };
 289
 290 }  // namespace hal
 291 }  // namespace bluetooth