OLD | NEW |
1 // Copyright 2014 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_ | 5 #ifndef DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_ |
6 #define DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_ | 6 #define DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_ |
7 | 7 |
8 #include <vector> | 8 #include <vector> |
9 | 9 |
10 #include "base/basictypes.h" | 10 #include "base/basictypes.h" |
11 #include "base/callback.h" | 11 #include "base/callback.h" |
12 #include "device/bluetooth/bluetooth_uuid.h" | 12 #include "device/bluetooth/bluetooth_utils.h" |
13 | 13 |
14 namespace device { | 14 namespace device { |
15 | 15 |
16 class BluetoothGattCharacteristic; | 16 class BluetoothGattCharacteristic; |
17 | 17 |
18 // BluetoothGattDescriptor represents a local or remote GATT characteristic | 18 // BluetoothGattDescriptor represents a local or remote GATT characteristic |
19 // descriptor. A GATT characteristic descriptor provides further information | 19 // descriptor. A GATT characteristic descriptor provides further information |
20 // about a characteristic's value. They can be used to describe the | 20 // about a characteristic's value. They can be used to describe the |
21 // characteristic's features or to control certain behaviors. | 21 // characteristic's features or to control certain behaviors. |
22 class BluetoothGattDescriptor { | 22 class BluetoothGattDescriptor { |
23 public: | 23 public: |
24 // The Bluetooth Specification declares several predefined descriptors that | 24 // The Bluetooth Specification declares several predefined descriptors that |
25 // profiles can use. The following are definitions for the list of UUIDs | 25 // profiles can use. The following are definitions for the list of UUIDs |
26 // and descriptions of the characteristic descriptors that they represent. | 26 // and descriptions of the characteristic descriptors that they represent. |
27 // Possible values for and further information on each descriptor can be found | 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 | 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. | 29 // optional and may not be present for a given characteristic. |
30 | 30 |
31 // The "Characteristic Extended Properties" descriptor. This defines | 31 // The "Characteristic Extended Properties" descriptor. This defines |
32 // additional "Characteristic Properties" which cannot fit into the allocated | 32 // additional "Characteristic Properties" which cannot fit into the allocated |
33 // single octet property field of a characteristic. The value is a bit field | 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: | 34 // and the two predefined bits, as per Bluetooth Core Specification v4.0, are: |
35 // | 35 // |
36 // - Reliable Write: 0x0001 | 36 // - Reliable Write: 0x0001 |
37 // - Writable Auxiliaries: 0x0002 | 37 // - Writable Auxiliaries: 0x0002 |
38 // | 38 // |
39 static const BluetoothUUID kCharacteristicExtendedPropertiesUuid; | 39 static const bluetooth_utils::UUID kCharacteristicExtendedPropertiesUuid; |
40 | 40 |
41 // The "Characteristic User Description" descriptor defines a UTF-8 string of | 41 // The "Characteristic User Description" descriptor defines a UTF-8 string of |
42 // variable size that is a user textual description of the associated | 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 | 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 | 44 // per characteristic. This descriptor can be written to if the "Writable |
45 // Auxiliaries" bit of the Characteristic Properties (via the "Characteristic | 45 // Auxiliaries" bit of the Characteristic Properties (via the "Characteristic |
46 // Extended Properties" descriptor) has been set. | 46 // Extended Properties" descriptor) has been set. |
47 static const BluetoothUUID kCharacteristicUserDescriptionUuid; | 47 static const bluetooth_utils::UUID kCharacteristicUserDescriptionUuid; |
48 | 48 |
49 // The "Client Characteristic Configuration" descriptor defines how the | 49 // The "Client Characteristic Configuration" descriptor defines how the |
50 // characteristic may be configured by a specific client. A server-side | 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 | 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 | 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 | 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 | 54 // and indications from a characteristic. The value is a bit field and the |
55 // predefined bits are: | 55 // predefined bits are: |
56 // | 56 // |
57 // - Default: 0x0000 | 57 // - Default: 0x0000 |
58 // - Notification: 0x0001 | 58 // - Notification: 0x0001 |
59 // - Indication: 0x0002 | 59 // - Indication: 0x0002 |
60 // | 60 // |
61 static const BluetoothUUID kClientCharacteristicConfigurationUuid; | 61 static const bluetooth_utils::UUID kClientCharacteristicConfigurationUuid; |
62 | 62 |
63 // The "Server Characteristic Configuration" descriptor defines how the | 63 // The "Server Characteristic Configuration" descriptor defines how the |
64 // characteristic may be configured for the server. There is one instance | 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 | 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 | 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 | 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 | 68 // advertising resources are available. The value is a bit field and the |
69 // predefined bits are: | 69 // predefined bits are: |
70 // | 70 // |
71 // - Default: 0x0000 | 71 // - Default: 0x0000 |
72 // - Broadcast: 0x0001 | 72 // - Broadcast: 0x0001 |
73 // | 73 // |
74 static const BluetoothUUID kServerCharacteristicConfigurationUuid; | 74 static const bluetooth_utils::UUID kServerCharacteristicConfigurationUuid; |
75 | 75 |
76 // The "Characteristic Presentation Format" declaration defines the format of | 76 // The "Characteristic Presentation Format" declaration defines the format of |
77 // the Characteristic Value. The value is composed of 7 octets which are | 77 // the Characteristic Value. The value is composed of 7 octets which are |
78 // divided into groups that represent different semantic meanings. For a | 78 // divided into groups that represent different semantic meanings. For a |
79 // detailed description of how the value of this descriptor should be | 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 | 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 | 81 // than one declaration of this descriptor exists for a characteristic, then a |
82 // "Characteristic Aggregate Format" descriptor must also exist for that | 82 // "Characteristic Aggregate Format" descriptor must also exist for that |
83 // characteristic. | 83 // characteristic. |
84 static const BluetoothUUID kCharacteristicPresentationFormatUuid; | 84 static const bluetooth_utils::UUID kCharacteristicPresentationFormatUuid; |
85 | 85 |
86 // The "Characteristic Aggregate Format" descriptor defines the format of an | 86 // The "Characteristic Aggregate Format" descriptor defines the format of an |
87 // aggragated characteristic value. In GATT's underlying protocol, ATT, each | 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. | 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 | 89 // Multiple characteristics can share the same instance(s) of a |
90 // "Characteristic Presentation Format" descriptor. The value of the | 90 // "Characteristic Presentation Format" descriptor. The value of the |
91 // "Characteristic Aggregate Format" descriptor contains a list of handles | 91 // "Characteristic Aggregate Format" descriptor contains a list of handles |
92 // that each refer to a "Characteristic Presentation Format" descriptor that | 92 // that each refer to a "Characteristic Presentation Format" descriptor that |
93 // is used by that characteristic. Hence, exactly one instance of this | 93 // is used by that characteristic. Hence, exactly one instance of this |
94 // descriptor must exist if more than one "Characteristic Presentation Format" | 94 // descriptor must exist if more than one "Characteristic Presentation Format" |
95 // descriptors exist for a characteristic. | 95 // descriptors exist for a characteristic. |
96 // | 96 // |
97 // Applications that are using the device::Bluetooth API do not have access to | 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 | 98 // the underlying handles and shouldn't use this descriptor to determine which |
99 // "Characteristic Presentation Format" desciptors belong to a characteristic. | 99 // "Characteristic Presentation Format" desciptors belong to a characteristic. |
100 // The API will construct a BluetoothGattDescriptor object for each instance | 100 // The API will construct a BluetoothGattDescriptor object for each instance |
101 // of "Characteristic Presentation Format" descriptor per instance of | 101 // of "Characteristic Presentation Format" descriptor per instance of |
102 // BluetoothGattCharacteristic that represents a remote characteristic. | 102 // BluetoothGattCharacteristic that represents a remote characteristic. |
103 // Similarly for local characteristics, implementations DO NOT need to create | 103 // Similarly for local characteristics, implementations DO NOT need to create |
104 // an instance of BluetoothGattDescriptor for this descriptor as this will be | 104 // an instance of BluetoothGattDescriptor for this descriptor as this will be |
105 // handled by the subsystem. | 105 // handled by the subsystem. |
106 static const BluetoothUUID kCharacteristicAggregateFormatUuid; | 106 static const bluetooth_utils::UUID kCharacteristicAggregateFormatUuid; |
107 | 107 |
108 // Interface for observing changes from a BluetoothGattDescriptor. | 108 // Interface for observing changes from a BluetoothGattDescriptor. |
109 // Properties of remote characteristic desciptors are received asynchonously. | 109 // Properties of remote characteristic desciptors are received asynchonously. |
110 // The Observer interface can be used to be notified when the initial values | 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 | 111 // of a characteristic descriptor are received as well as when successive |
112 // changes occur during its life cycle. | 112 // changes occur during its life cycle. |
113 class Observer { | 113 class Observer { |
114 public: | 114 public: |
115 // Called when the UUID of |descriptor| has changed. | 115 // Called when the UUID of |descriptor| has changed. |
116 virtual void UuidChanged( | 116 virtual void UuidChanged( |
117 BluetoothGattDescriptor* descriptor, | 117 BluetoothGattDescriptor* descriptor, |
118 const BluetoothUUID& uuid) {} | 118 const bluetooth_utils::UUID& uuid) {} |
119 | 119 |
120 // Called when the current value of |descriptor| has changed. | 120 // Called when the current value of |descriptor| has changed. |
121 virtual void ValueChanged( | 121 virtual void ValueChanged( |
122 BluetoothGattDescriptor* descriptor, | 122 BluetoothGattDescriptor* descriptor, |
123 const std::vector<uint8>& value) {} | 123 const std::vector<uint8>& value) {} |
124 }; | 124 }; |
125 | 125 |
126 // The ErrorCallback is used by methods to asynchronously report errors. | 126 // The ErrorCallback is used by methods to asynchronously report errors. |
127 typedef base::Callback<void(const std::string&)> ErrorCallback; | 127 typedef base::Callback<void(const std::string&)> ErrorCallback; |
128 | 128 |
(...skipping 17 matching lines...) Expand all Loading... |
146 // initial cached value |value|. |value| will be cached and returned for read | 146 // initial cached value |value|. |value| will be cached and returned for read |
147 // requests and automatically modified for write requests by default, unless | 147 // requests and automatically modified for write requests by default, unless |
148 // an instance of BluetoothGattService::Delegate has been provided to the | 148 // an instance of BluetoothGattService::Delegate has been provided to the |
149 // associated BluetoothGattService instance, in which case the delegate will | 149 // associated BluetoothGattService instance, in which case the delegate will |
150 // handle the read and write requests. | 150 // handle the read and write requests. |
151 // | 151 // |
152 // Currently, only custom UUIDs, |kCharacteristicDescriptionUuid|, and | 152 // Currently, only custom UUIDs, |kCharacteristicDescriptionUuid|, and |
153 // |kCharacteristicPresentationFormat| are supported for locally hosted | 153 // |kCharacteristicPresentationFormat| are supported for locally hosted |
154 // descriptors. This method will return NULL if |uuid| is any one of the | 154 // descriptors. This method will return NULL if |uuid| is any one of the |
155 // unsupported predefined descriptor UUIDs. | 155 // unsupported predefined descriptor UUIDs. |
156 static BluetoothGattDescriptor* Create(const BluetoothUUID& uuid, | 156 static BluetoothGattDescriptor* Create(const bluetooth_utils::UUID& uuid, |
157 const std::vector<uint8>& value); | 157 const std::vector<uint8>& value); |
158 | 158 |
159 // The Bluetooth-specific UUID of the characteristic descriptor. | 159 // The Bluetooth-specific UUID of the characteristic descriptor. |
160 virtual const BluetoothUUID& GetUuid() const = 0; | 160 virtual const bluetooth_utils::UUID& GetUuid() const = 0; |
161 | 161 |
162 // Returns true, if this characteristic descriptor is hosted locally. If | 162 // Returns true, if this characteristic descriptor is hosted locally. If |
163 // false, then this instance represents a remote descriptor. | 163 // false, then this instance represents a remote descriptor. |
164 virtual bool IsLocal() const = 0; | 164 virtual bool IsLocal() const = 0; |
165 | 165 |
166 // Returns a pointer to the GATT characteristic that this characteristic | 166 // Returns a pointer to the GATT characteristic that this characteristic |
167 // descriptor belongs to. | 167 // descriptor belongs to. |
168 virtual const BluetoothGattCharacteristic* GetCharacteristic() const = 0; | 168 virtual const BluetoothGattCharacteristic* GetCharacteristic() const = 0; |
169 | 169 |
170 // Sends a read request to a remote characteristic descriptor to read its | 170 // Sends a read request to a remote characteristic descriptor to read its |
(...skipping 17 matching lines...) Expand all Loading... |
188 BluetoothGattDescriptor(); | 188 BluetoothGattDescriptor(); |
189 virtual ~BluetoothGattDescriptor(); | 189 virtual ~BluetoothGattDescriptor(); |
190 | 190 |
191 private: | 191 private: |
192 DISALLOW_COPY_AND_ASSIGN(BluetoothGattDescriptor); | 192 DISALLOW_COPY_AND_ASSIGN(BluetoothGattDescriptor); |
193 }; | 193 }; |
194 | 194 |
195 } // namespace device | 195 } // namespace device |
196 | 196 |
197 #endif // DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_ | 197 #endif // DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_ |
OLD | NEW |