service/low_energy_client.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 <atomic>
  20 #include <functional>
  21 #include <map>
  22 #include <mutex>
  23
  24 #include <base/macros.h>
  25
  26 #include "service/bluetooth_instance.h"
  27 #include "service/common/bluetooth/advertise_data.h"
  28 #include "service/common/bluetooth/advertise_settings.h"
  29 #include "service/common/bluetooth/low_energy_constants.h"
  30 #include "service/common/bluetooth/uuid.h"
  31 #include "service/hal/bluetooth_gatt_interface.h"
  32
  33 namespace 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.
  38 class LowEnergyClient : private hal::BluetoothGattInterface::ClientObserver,
  39                         public BluetoothInstance {
  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& advertise_settings() const {
  69    return advertise_settings_;
  70   }
  71
  72   // BluetoothClientInstace overrides:
  73   const UUID& GetAppIdentifier() const override;
  74   int GetInstanceId() const override;
  75
  76  private:
  77   friend class LowEnergyClientFactory;
  78
  79   // Constructor shouldn't be called directly as instances are meant to be
  80   // obtained from the factory.
  81   LowEnergyClient(const UUID& uuid, int client_id);
  82
  83   // BluetoothGattInterface::ClientObserver overrides:
  84   void MultiAdvEnableCallback(
  85       hal::BluetoothGattInterface* gatt_iface,
  86       int client_id, int status) override;
  87   void MultiAdvDataCallback(
  88       hal::BluetoothGattInterface* gatt_iface,
  89       int client_id, int status) override;
  90   void MultiAdvDisableCallback(
  91       hal::BluetoothGattInterface* gatt_iface,
  92       int client_id, int status) override;
  93
  94   // Helper method called from SetAdvertiseData/SetScanResponse.
  95   bt_status_t SetAdvertiseData(
  96       hal::BluetoothGattInterface* gatt_iface,
  97       const AdvertiseData& data,
  98       bool set_scan_rsp);
  99
 100   // Handles deferred advertise/scan-response data updates. We set the data if
 101   // there's data to be set, otherwise we either defer it if advertisements
 102   // aren't enabled or do nothing.
 103   void HandleDeferredAdvertiseData(hal::BluetoothGattInterface* gatt_iface);
 104
 105   // Calls and clears the pending callbacks.
 106   void InvokeAndClearStartCallback(BLEStatus status);
 107   void InvokeAndClearStopCallback(BLEStatus status);
 108
 109   // See getters above for documentation.
 110   UUID app_identifier_;
 111   int client_id_;
 112
 113   // Protects advertising-related members below.
 114   std::mutex adv_fields_lock_;
 115
 116   // The advertising and scan response data fields that will be sent to the
 117   // controller.
 118   AdvertiseData adv_data_;
 119   AdvertiseData scan_response_;
 120   std::atomic_bool adv_data_needs_update_;
 121   std::atomic_bool scan_rsp_needs_update_;
 122
 123   // Latest advertising settings.
 124   AdvertiseSettings advertise_settings_;
 125
 126   // Whether or not there is a pending call to update advertising or scan
 127   // response data.
 128   std::atomic_bool is_setting_adv_data_;
 129
 130   std::atomic_bool adv_started_;
 131   std::unique_ptr<StatusCallback> adv_start_callback_;
 132   std::unique_ptr<StatusCallback> adv_stop_callback_;
 133
 134   DISALLOW_COPY_AND_ASSIGN(LowEnergyClient);
 135 };
 136
 137 // LowEnergyClientFactory is used to register and obtain a per-application
 138 // LowEnergyClient instance. Users should call RegisterInstance to obtain their
 139 // own unique LowEnergyClient instance that has been registered with the
 140 // Bluetooth stack.
 141 class LowEnergyClientFactory
 142     : private hal::BluetoothGattInterface::ClientObserver,
 143       public BluetoothInstanceFactory {
 144  public:
 145   // Don't construct/destruct directly except in tests. Instead, obtain a handle
 146   // from an Adapter instance.
 147   LowEnergyClientFactory();
 148   ~LowEnergyClientFactory() override;
 149
 150   // BluetoothInstanceFactory override:
 151   bool RegisterInstance(const UUID& uuid,
 152                         const RegisterCallback& callback) override;
 153
 154  private:
 155   // BluetoothGattInterface::ClientObserver overrides:
 156   void RegisterClientCallback(
 157       hal::BluetoothGattInterface* gatt_iface,
 158       int status, int client_id,
 159       const bt_uuid_t& app_uuid) override;
 160
 161   // Map of pending calls to register.
 162   std::mutex pending_calls_lock_;
 163   std::map<UUID, RegisterCallback> pending_calls_;
 164
 165   DISALLOW_COPY_AND_ASSIGN(LowEnergyClientFactory);
 166 };
 167
 168 }  // namespace bluetooth