Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 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_DESCRIPTOR_H_ |
| 6 | #define DEVICE_BLUETOOTH_GATT_DESCRIPTOR_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 BluetoothGattCharacteristic; |
| 17 | |
| 18 | // BluetoothGattDescriptor represents a local or remote GATT characteristic |
| 19 | // descriptor. A GATT characteristic descriptor provides further information |
| 20 | // about a characteristic's value. They can be used to describe the |
| 21 | // characteristic's features or to control certain behaviors. |
| 22 | class BluetoothGattDescriptor { |
| 23 | public: |
| 24 | // The Bluetooth Specification declares several predefined descriptors that |
| 25 | // profiles can use. The following are definitions for the list of UUIDs |
| 26 | // and descriptions of the characteristic descriptors that they represent. |
| 27 | // Possible values for and further information on each descriptor can be found |
| 28 | // in Core v4.0, Volume 3, Part G, Section 3.3.3. All of these desciptors are |
| 29 | // optional and may not be present for a given characteristic. |
| 30 | |
| 31 | // The "Characteristic Extended Properties" descriptor. This defines |
| 32 | // additional "Characteristic Properties" which cannot fit into the allocated |
| 33 | // single octet property field of a characteristic. The value is a bit field |
| 34 | // and the two predefined bits, as per Bluetooth Core Specification v4.0, are: |
| 35 | // |
| 36 | // - Reliable Write: 0x0001 |
| 37 | // - Writable Auxiliaries: 0x0002 |
| 38 | // |
| 39 | static const bluetooth_utils::UUID kCharacteristicExtendedPropertiesUuid; |
| 40 | |
| 41 | // The "Characteristic User Description" descriptor defines a UTF-8 string of |
| 42 | // variable size that is a user textual description of the associated |
| 43 | // characteristic's value. There can be only one instance of this descriptor |
| 44 | // per characteristic. This descriptor can be written to if the "Writable |
| 45 | // Auxiliaries" bit of the Characteristic Properties (via the "Characteristic |
| 46 | // Extended Properties" descriptor) has been set. |
| 47 | static const bluetooth_utils::UUID kCharacteristicUserDescriptionUuid; |
| 48 | |
| 49 | // The "Client Characteristic Configuration" descriptor defines how the |
| 50 | // characteristic may be configured by a specific client. A server-side |
| 51 | // instance of this descriptor exists for each client that has bonded with |
| 52 | // the server and the value can be read and written by that client only. As |
| 53 | // of Core v4.0, this descriptor is used by clients to set up notifications |
| 54 | // and indications from a characteristic. The value is a bit field and the |
| 55 | // predefined bits are: |
| 56 | // |
| 57 | // - Default: 0x0000 |
| 58 | // - Notification: 0x0001 |
| 59 | // - Indication: 0x0002 |
| 60 | // |
| 61 | static const bluetooth_utils::UUID kClientCharacteristicConfigurationUuid; |
| 62 | |
| 63 | // The "Server Characteristic Configuration" descriptor defines how the |
| 64 | // characteristic may be configured for the server. There is one instance |
| 65 | // of this descriptor for all clients and setting the value of this descriptor |
| 66 | // affects its configuration for all clients. As of Core v4.0, this descriptor |
| 67 | // is used to set up the server to broadcast the characteristic value if |
| 68 | // advertising resources are available. The value is a bit field and the |
| 69 | // predefined bits are: |
| 70 | // |
| 71 | // - Default: 0x0000 |
| 72 | // - Broadcast: 0x0001 |
| 73 | // |
| 74 | static const bluetooth_utils::UUID kServerCharacteristicConfigurationUuid; |
| 75 | |
| 76 | // The "Characteristic Presentation Format" declaration defines the format of |
| 77 | // the Characteristic Value. The value is composed of 7 octets which are |
| 78 | // divided into groups that represent different semantic meanings. For a |
| 79 | // detailed description of how the value of this descriptor should be |
| 80 | // interpreted, refer to Core v4.0, Volume 3, Part G, Section 3.3.3.5. If more |
| 81 | // than one declaration of this descriptor exists for a characteristic, then a |
| 82 | // "Characteristic Aggregate Format" descriptor must also exist for that |
| 83 | // characteristic. |
| 84 | static const bluetooth_utils::UUID kCharacteristicPresentationFormatUuid; |
| 85 | |
| 86 | // The "Characteristic Aggregate Format" descriptor defines the format of an |
| 87 | // aggragated characteristic value. In GATT's underlying protocol, ATT, each |
| 88 | // attribute is identified by a handle that is unique for the hosting server. |
| 89 | // Multiple characteristics can share the same instance(s) of a |
| 90 | // "Characteristic Presentation Format" descriptor. The value of the |
| 91 | // "Characteristic Aggregate Format" descriptor contains a list of handles |
| 92 | // that each refer to a "Characteristic Presentation Format" descriptor that |
| 93 | // is used by that characteristic. Hence, exactly one instance of this |
| 94 | // descriptor must exist if more than one "Characteristic Presentation Format" |
| 95 | // descriptors exist for a characteristic. |
| 96 | // |
| 97 | // Applications that are using the device::Bluetooth API do not have access to |
| 98 | // the underlying handles and shouldn't use this descriptor to determine which |
| 99 | // "Characteristic Presentation Format" desciptors belong to a characteristic. |
| 100 | // The API will construct a BluetoothGattDescriptor object for each instance |
| 101 | // of "Characteristic Presentation Format" descriptor per instance of |
| 102 | // BluetoothGattCharacteristic that represents a remote characteristic. |
| 103 | // Similarly for local characteristics, implementations DO NOT need to create |
| 104 | // an instance of BluetoothGattDescriptor for this descriptor as this will be |
| 105 | // handled by the subsystem. |
| 106 | static const bluetooth_utils::UUID kCharacteristicAggregateFormatUuid; |
| 107 | |
| 108 | // Interface for observing changes from a BluetoothGattDescriptor. |
| 109 | // Properties of remote characteristic desciptors are received asynchonously. |
| 110 | // The Observer interface can be used to be notified when the initial values |
| 111 | // of a characteristic descriptor are received as well as when successive |
| 112 | // changes occur during its life cycle. |
| 113 | class Observer { |
| 114 | public: |
| 115 | // Called when the UUID of |descriptor| has changed. |
| 116 | virtual void UuidChanged( |
| 117 | BluetoothGattDescriptor* descriptor, |
| 118 | const bluetooth_utils::UUID& uuid) {} |
| 119 | |
| 120 | // Called when the current value of |descriptor| has changed. |
| 121 | virtual void ValueChanged( |
| 122 | BluetoothGattDescriptor* descriptor, |
| 123 | const std::vector<uint8>& value) {} |
| 124 | }; |
| 125 | |
| 126 | // The ErrorCallback is used by methods to asynchronously report errors. |
| 127 | typedef base::Callback<void(const std::string&)> ErrorCallback; |
| 128 | |
| 129 | // The ValueCallback is used to return the value of a remote characteristic |
| 130 | // descriptor upon a read request. |
| 131 | typedef base::Callback<void(const std::vector<uint8>&)> ValueCallback; |
| 132 | |
| 133 | // Adds and removes observers for events on this GATT characteristic |
| 134 | // descriptor. If monitoring multiple descriptors, check the |descriptor| |
| 135 | // parameter of observer methods to determine which characteristic is issuing |
| 136 | // the event. |
| 137 | virtual void AddObserver(Observer* observer) = 0; |
| 138 | virtual void RemoveObserver(Observer* observer) = 0; |
| 139 | |
| 140 | // Constructs a BluetoothGattDescriptor that can be associated with a local |
| 141 | // GATT characteristic when the adapter is in the peripheral role. To |
| 142 | // associate the returned descriptor with a characteristic, add it to a local |
| 143 | // characteristic by calling BluetoothGattCharacteristic::AddDescriptor. |
| 144 | // |
| 145 | // This method constructs a characteristic descriptor with UUID |uuid| and the |
| 146 | // initial cached value |value|. |value| will be cached and returned for read |
| 147 | // requests and automatically modified for write requests by default, unless |
| 148 | // an instance of BluetoothGattService::Delegate has been provided to the |
| 149 | // associated BluetoothGattService instance, in which case the delegate will |
| 150 | // handle the read and write requests. |
| 151 | // |
| 152 | // Currently, only custom UUIDs, |kCharacteristicDescriptionUuid|, and |
| 153 | // |kCharacteristicPresentationFormat| are supported for locally hosted |
| 154 | // descriptors. This method will return NULL if |uuid| is any one of the |
| 155 | // unsupported predefined descriptor UUIDs. |
| 156 | static BluetoothGattDescriptor* Create(const bluetooth_utils::UUID& uuid, |
| 157 | const std::vector<uint8>& value); |
| 158 | |
| 159 | // The Bluetooth-specific UUID of the characteristic descriptor. |
| 160 | virtual const bluetooth_utils::UUID& GetUuid() const = 0; |
| 161 | |
| 162 | // Returns true, if this characteristic descriptor is hosted locally. If |
| 163 | // false, then this instance represents a remote descriptor. |
| 164 | virtual bool IsLocal() const = 0; |
| 165 | |
| 166 | // Returns a pointer to the GATT characteristic that this characteristic |
| 167 | // descriptor belongs to. |
| 168 | virtual const BluetoothGattCharacteristic* GetCharacteristic() const = 0; |
| 169 | |
| 170 | // Sends a read request to a remote characteristic descriptor to read its |
| 171 | // value. |callback| is called to return the read value on success and |
| 172 | // |error_callback| is called for failures. |
| 173 | virtual void ReadRemoteDescriptor(const ValueCallback& callback, |
| 174 | const ErrorCallback& error_callback) = 0; |
| 175 | |
| 176 | // Sends a write request to a remote characteristic descriptor, to modify the |
| 177 | // value of the descriptor starting at offset |offset| with the new value |
| 178 | // |new_value|. |callback| is called to signal success and |error_callback| |
| 179 | // for failures. This method only applies to remote descriptors and will fail |
| 180 | // for those that are locally hosted. |
| 181 | virtual void WriteRemoteDescriptor( |
| 182 | int offset, |
| 183 | const std::vector<uint8>& new_value, |
| 184 | const base::Closure& callback, |
| 185 | const ErrorCallback& error_callback) = 0; |
| 186 | |
| 187 | protected: |
| 188 | BluetoothGattDescriptor(); |
| 189 | virtual ~BluetoothGattDescriptor(); |
| 190 | |
| 191 | private: |
| 192 | DISALLOW_COPY_AND_ASSIGN(BluetoothGattDescriptor); |
| 193 | }; |
| 194 | |
| 195 | } // namespace device |
| 196 | |
| 197 | #endif // DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_ |