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