| 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 |