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