src/device/bluetooth/bluetooth_gatt_characteristic.h

   1 // Copyright 2014 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_GATT_CHARACTERISTIC_H_
   6 #define DEVICE_BLUETOOTH_GATT_CHARACTERISTIC_H_
   7
   8 #include <vector>
   9
  10 #include "base/basictypes.h"
  11 #include "base/callback.h"
  12 #include "device/bluetooth/bluetooth_utils.h"
  13
  14 namespace device {
  15
  16 class BluetoothGattDescriptor;
  17 class BluetoothGattService;
  18
  19 // BluetoothGattCharacteristic represents a local or remote GATT characteristic.
  20 // A GATT characteristic is a basic data element used to construct a GATT
  21 // service. Hence, instances of a BluetoothGattCharacteristic are associated
  22 // with a BluetoothGattService. There are two ways in which this class is used:
  23 //
  24 //   1. To represent GATT characteristics that belong to a service hosted by a
  25 //      a remote device. In this case the characteristic will be constructed by
  26 //      the subsystem.
  27 //   2. To represent GATT characteristics that belong to a locally hosted
  28 //      service. To achieve this, users can construct instances of
  29 //      BluetoothGattCharacteristic directly and add it to the desired
  30 //      BluetoothGattService instance that represents a local service.
  31 class BluetoothGattCharacteristic {
  32  public:
  33   // Values representing the possible properties of a characteristic, which
  34   // define how the characteristic can be used. Each of these properties serve
  35   // a role as defined in the Bluetooth Specification.
  36   // |kPropertyExtendedProperties| is a special property that, if present,
  37   // indicates that there is a characteristic descriptor (namely the
  38   // "Characteristic Extended Properties Descriptor" with UUID 0x2900) that
  39   // contains additional properties pertaining to the characteristic.
  40   enum Property {
  41     kPropertyNone = 0,
  42     kPropertyBroadcast = 1 << 0,
  43     kPropertyRead = 1 << 1,
  44     kPropertyWriteWithoutResponse = 1 << 2,
  45     kPropertyWrite = 1 << 3,
  46     kPropertyNotify = 1 << 4,
  47     kPropertyIndicate = 1 << 5,
  48     kPropertyAuthenticatedSignedWrites = 1 << 6,
  49     kPropertyExtendedProperties = 1 << 7
  50   };
  51   typedef uint32 Properties;
  52
  53   // Values representing read, write, and encryption permissions for a
  54   // characteristic's value. While attribute permissions for all GATT
  55   // definitions have been set by the Bluetooth specification, characteristic
  56   // value permissions are left up to the higher-level profile.
  57   //
  58   // Attribute permissions are distinct from the characteristic properties. For
  59   // example, a characteristic may have the property |kPropertyRead| to make
  60   // clients know that it is possible to read the characteristic value and have
  61   // the permission |kPermissionReadEncrypted| to require a secure connection.
  62   // It is up to the application to properly specify the permissions and
  63   // properties for a local characteristic.
  64   enum Permission {
  65     kPermissionNone = 0,
  66     kPermissionRead = 1 << 0,
  67     kPermissionWrite = 1 << 1,
  68     kPermissionReadEncrypted = 1 << 2,
  69     kPermissionWriteEncrypted = 1 << 3
  70   };
  71   typedef uint32 Permissions;
  72
  73   // Interface for observing changes from a BluetoothGattCharacteristic.
  74   // Properties of remote characteristics are received asynchonously. The
  75   // Observer interface can be used to be notified when the initial values of a
  76   // characteristic are received as well as when successive changes occur during
  77   // its life cycle.
  78   class Observer {
  79    public:
  80     // Called when the UUID of |characteristic| has changed.
  81     virtual void UuidChanged(
  82         BluetoothGattCharacteristic* characteristic,
  83         const bluetooth_utils::UUID& uuid) {}
  84
  85     // Called when the current value of |characteristic| has changed.
  86     virtual void ValueChanged(
  87         BluetoothGattCharacteristic* characteristic,
  88         const std::vector<uint8>& value) {}
  89
  90     // Called when the descriptors that are associated with |characteristic|
  91     // have changed.
  92     virtual void DescriptorsChanged(
  93         BluetoothGattCharacteristic* characteristic,
  94         const std::vector<BluetoothGattDescriptor*>& descriptors) {}
  95   };
  96
  97   // The ErrorCallback is used by methods to asynchronously report errors.
  98   typedef base::Callback<void(const std::string&)> ErrorCallback;
  99
 100   // The ValueCallback is used to return the value of a remote characteristic
 101   // upon a read request.
 102   typedef base::Callback<void(const std::vector<uint8>&)> ValueCallback;
 103
 104   // Adds and removes observers for events on this GATT characteristic. If
 105   // monitoring multiple characteristics, check the |characteristic| parameter
 106   // of observer methods to determine which characteristic is issuing the event.
 107   virtual void AddObserver(Observer* observer) = 0;
 108   virtual void RemoveObserver(Observer* observer) = 0;
 109
 110   // Constructs a BluetoothGattCharacteristic that can be associated with a
 111   // local GATT service when the adapter is in the peripheral role. To
 112   // associate the returned characteristic with a service, add it to a local
 113   // service by calling BluetoothGattService::AddCharacteristic.
 114   //
 115   // This method constructs a characteristic with UUID |uuid|, initial cached
 116   // value |value|, properties |properties|, and permissions |permissions|.
 117   // |value| will be cached and returned for read requests and automatically set
 118   // for write requests by default, unless an instance of
 119   // BluetoothGattService::Delegate has been provided to the associated
 120   // BluetoothGattService instance, in which case the delegate will handle read
 121   // and write requests.
 122   //
 123   // NOTE: Don't explicitly set |kPropertyExtendedProperties| in |properties|.
 124   // Instead, create and add a BluetoothGattDescriptor that represents the
 125   // "Characteristic Extended Properties" descriptor and this will automatically
 126   // set the correspoding bit in the characteristic's properties field. If
 127   // |properties| has |kPropertyExtendedProperties| set, it will be ignored.
 128   static BluetoothGattCharacteristic* Create(const bluetooth_utils::UUID& uuid,
 129                                              const std::vector<uint8>& value,
 130                                              Properties properties,
 131                                              Permissions permissions);
 132
 133   // The Bluetooth-specific UUID of the characteristic.
 134   virtual const bluetooth_utils::UUID& GetUuid() const = 0;
 135
 136   // Returns true, if this characteristic is hosted locally. If false, then this
 137   // instance represents a remote GATT characteristic.
 138   virtual bool IsLocal() const = 0;
 139
 140   // Returns a pointer to the GATT service this characteristic belongs to.
 141   virtual const BluetoothGattService* GetService() const = 0;
 142
 143   // Returns the list of GATT characteristic descriptors that provide more
 144   // information about this characteristic.
 145   virtual const std::vector<BluetoothGattDescriptor*>
 146       GetDescriptors() const = 0;
 147
 148   // Adds a characteristic descriptor to the locally hosted characteristic
 149   // represented by this instance. This method only makes sense for local
 150   // characteristics and won't have an effect if this instance represents a
 151   // remote GATT service and will return false. This method takes ownership
 152   // of |descriptor|.
 153   virtual bool AddDescriptor(BluetoothGattDescriptor* descriptor) = 0;
 154
 155   // For locally hosted characteristics, updates the characteristic's value.
 156   // This will update the value that is visible to remote devices and send out
 157   // any notifications and indications that have been configured. This method
 158   // can be used in place of, and in conjunction with,
 159   // BluetoothGattService::Delegate methods to send updates to remote devices,
 160   // or simply to set update the cached value for read requests without having
 161   // to implement the delegate methods.
 162   //
 163   // This method only makes sense for local characteristics and does nothing and
 164   // returns false if this instance represents a remote characteristic.
 165   virtual bool UpdateValue(const std::vector<uint8>& value) = 0;
 166
 167   // Sends a read request to a remote characteristic to read its value.
 168   // |callback| is called to return the read value on success and
 169   // |error_callback| is called for failures.
 170   virtual void ReadRemoteCharacteristic(
 171       const ValueCallback& callback,
 172       const ErrorCallback& error_callback) = 0;
 173
 174   // Sends a write request to a remote characteristic, to modify the
 175   // characteristic's value starting at offset |offset| with the new value
 176   // |new_value|. |callback| is called to signal success and |error_callback|
 177   // for failures. This method only applies to remote characteristics and will
 178   // fail for those that are locally hosted.
 179   virtual void WriteRemoteCharacteristic(
 180       int offset,
 181       const std::vector<uint8>& new_value,
 182       const base::Closure& callback,
 183       const ErrorCallback& error_callback) = 0;
 184
 185  protected:
 186   BluetoothGattCharacteristic();
 187   virtual ~BluetoothGattCharacteristic();
 188
 189  private:
 190   DISALLOW_COPY_AND_ASSIGN(BluetoothGattCharacteristic);
 191 };
 192
 193 }  // namespace device
 194
 195 #endif  // DEVICE_BLUETOOTH_GATT_CHARACTERISTIC_H_