OLD | NEW |
1 // Copyright 2016 The Chromium Authors. All rights reserved. | 1 // Copyright 2016 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_REMOTE_GATT_CHARACTERISTIC_H_ | 5 #ifndef DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ |
6 #define DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ | 6 #define DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ |
7 | 7 |
8 #include <stdint.h> | 8 #include <stdint.h> |
9 | |
10 #include <queue> | |
11 #include <set> | |
12 #include <string> | 9 #include <string> |
13 #include <vector> | 10 #include <vector> |
14 | 11 |
15 #include "base/callback.h" | 12 #include "base/callback.h" |
16 #include "base/callback_forward.h" | 13 #include "base/callback_forward.h" |
17 #include "base/macros.h" | 14 #include "base/macros.h" |
18 #include "base/memory/weak_ptr.h" | |
19 #include "device/bluetooth/bluetooth_export.h" | 15 #include "device/bluetooth/bluetooth_export.h" |
20 #include "device/bluetooth/bluetooth_gatt_characteristic.h" | 16 #include "device/bluetooth/bluetooth_gatt_characteristic.h" |
21 #include "device/bluetooth/bluetooth_remote_gatt_service.h" | |
22 #include "device/bluetooth/bluetooth_uuid.h" | 17 #include "device/bluetooth/bluetooth_uuid.h" |
23 | 18 |
24 namespace device { | 19 namespace device { |
25 | 20 |
26 class BluetoothGattNotifySession; | 21 class BluetoothGattNotifySession; |
27 class BluetoothRemoteGattDescriptor; | 22 class BluetoothRemoteGattDescriptor; |
28 class BluetoothRemoteGattService; | 23 class BluetoothRemoteGattService; |
29 | 24 |
30 // BluetoothRemoteGattCharacteristic represents a remote GATT characteristic. | 25 // BluetoothRemoteGattCharacteristic represents a remote GATT characteristic. |
31 // This class is used to represent GATT characteristics that belong to a service | 26 // This class is used to represent GATT characteristics that belong to a service |
(...skipping 18 matching lines...) Expand all Loading... |
50 NotifySessionCallback; | 45 NotifySessionCallback; |
51 | 46 |
52 // Returns the value of the characteristic. For remote characteristics, this | 47 // Returns the value of the characteristic. For remote characteristics, this |
53 // is the most recently cached value. For local characteristics, this is the | 48 // is the most recently cached value. For local characteristics, this is the |
54 // most recently updated value or the value retrieved from the delegate. | 49 // most recently updated value or the value retrieved from the delegate. |
55 virtual const std::vector<uint8_t>& GetValue() const = 0; | 50 virtual const std::vector<uint8_t>& GetValue() const = 0; |
56 | 51 |
57 // Returns a pointer to the GATT service this characteristic belongs to. | 52 // Returns a pointer to the GATT service this characteristic belongs to. |
58 virtual BluetoothRemoteGattService* GetService() const = 0; | 53 virtual BluetoothRemoteGattService* GetService() const = 0; |
59 | 54 |
| 55 // Returns whether or not this characteristic is currently sending value |
| 56 // updates in the form of a notification or indication. |
| 57 virtual bool IsNotifying() const = 0; |
| 58 |
60 // Returns the list of GATT characteristic descriptors that provide more | 59 // Returns the list of GATT characteristic descriptors that provide more |
61 // information about this characteristic. | 60 // information about this characteristic. |
62 virtual std::vector<BluetoothRemoteGattDescriptor*> GetDescriptors() | 61 virtual std::vector<BluetoothRemoteGattDescriptor*> GetDescriptors() |
63 const = 0; | 62 const = 0; |
64 | 63 |
65 // Returns the GATT characteristic descriptor with identifier |identifier| if | 64 // Returns the GATT characteristic descriptor with identifier |identifier| if |
66 // it belongs to this GATT characteristic. | 65 // it belongs to this GATT characteristic. |
67 virtual BluetoothRemoteGattDescriptor* GetDescriptor( | 66 virtual BluetoothRemoteGattDescriptor* GetDescriptor( |
68 const std::string& identifier) const = 0; | 67 const std::string& identifier) const = 0; |
69 | 68 |
70 // Returns the GATT characteristic descriptors that match |uuid|. There may be | 69 // Returns the GATT characteristic descriptors that match |uuid|. There may be |
71 // multiple, as illustrated by Core Bluetooth Specification [V4.2 Vol 3 Part G | 70 // multiple, as illustrated by Core Bluetooth Specification [V4.2 Vol 3 Part G |
72 // 3.3.3.5 Characteristic Presentation Format]. | 71 // 3.3.3.5 Characteristic Presentation Format]. |
73 std::vector<BluetoothRemoteGattDescriptor*> GetDescriptorsByUUID( | 72 std::vector<BluetoothRemoteGattDescriptor*> GetDescriptorsByUUID( |
74 const BluetoothUUID& uuid) const; | 73 const BluetoothUUID& uuid); |
75 | |
76 // Get a weak pointer to the characteristic. | |
77 base::WeakPtr<BluetoothRemoteGattCharacteristic> GetWeakPtr(); | |
78 | |
79 // Returns whether or not this characteristic is currently sending value | |
80 // updates in the form of a notification or indication. | |
81 // | |
82 // If your code wants to receive notifications, you MUST call | |
83 // StartNotifySession and hold on to the resulting session object for as long | |
84 // as you want to keep receiving notifications. Even if this method returns | |
85 // true, and you are able to see the notifications coming in, you have no | |
86 // guarantee that the notifications will keep flowing for as long as you | |
87 // need, unless you open your own session. | |
88 virtual bool IsNotifying() const; | |
89 | 74 |
90 // Starts a notify session for the remote characteristic, if it supports | 75 // Starts a notify session for the remote characteristic, if it supports |
91 // notifications/indications. On success, the characteristic starts sending | 76 // notifications/indications. On success, the characteristic starts sending |
92 // value notifications and |callback| is called with a session object whose | 77 // value notifications and |callback| is called with a session object whose |
93 // ownership belongs to the caller. |error_callback| is called on errors. | 78 // ownership belongs to the caller. |error_callback| is called on errors. |
94 // | 79 // |
95 // This method handles all logic regarding multiple sessions so that | 80 // Writes to the Client Characteristic Configuration descriptor to enable |
96 // specific platform implementations of the remote characteristic class | 81 // notifications/indications. Core Bluetooth Specification [V4.2 Vol 3 Part G |
97 // do not have to. Rather than overriding this method, it is recommended | 82 // Section 3.3.1.1. Characteristic Properties] requires this descriptor to be |
98 // to override the SubscribeToNotifications method below. | 83 // present when notifications/indications are supported. If the descriptor is |
99 // | 84 // not present |error_callback| will be run. |
100 // The code in SubscribeToNotifications writes to the Client Characteristic | |
101 // Configuration descriptor to enable notifications/indications. Core | |
102 // Bluetooth Specification [V4.2 Vol 3 Part G Section 3.3.1.1. Characteristic | |
103 // Properties] requires this descriptor to be present when | |
104 // notifications/indications are supported. If the descriptor is not present | |
105 // |error_callback| will be run. | |
106 // | |
107 // Writing a non-zero value to the remote characteristic's Client | |
108 // Characteristic Configuration descriptor, causes the remote characteristic | |
109 // to start sending us notifications whenever the characteristic's value | |
110 // changes. When a new notification is received, | |
111 // BluetoothAdapterObserver::GattCharacteristicValueChanged is called with | |
112 // the characteristic's new value. | |
113 // | |
114 // To stop the flow of notifications, simply call the Stop method on the | |
115 // BluetoothGattNotifySession object that you received in |callback|. | |
116 virtual void StartNotifySession(const NotifySessionCallback& callback, | 85 virtual void StartNotifySession(const NotifySessionCallback& callback, |
117 const ErrorCallback& error_callback); | 86 const ErrorCallback& error_callback) = 0; |
118 | 87 |
119 // Sends a read request to a remote characteristic to read its value. | 88 // Sends a read request to a remote characteristic to read its value. |
120 // |callback| is called to return the read value on success and | 89 // |callback| is called to return the read value on success and |
121 // |error_callback| is called for failures. | 90 // |error_callback| is called for failures. |
122 virtual void ReadRemoteCharacteristic( | 91 virtual void ReadRemoteCharacteristic( |
123 const ValueCallback& callback, | 92 const ValueCallback& callback, |
124 const ErrorCallback& error_callback) = 0; | 93 const ErrorCallback& error_callback) = 0; |
125 | 94 |
126 // Sends a write request to a remote characteristic, to modify the | 95 // Sends a write request to a remote characteristic, to modify the |
127 // characteristic's value with the new value |new_value|. |callback| is | 96 // characteristic's value with the new value |new_value|. |callback| is |
128 // called to signal success and |error_callback| for failures. This method | 97 // called to signal success and |error_callback| for failures. This method |
129 // only applies to remote characteristics and will fail for those that are | 98 // only applies to remote characteristics and will fail for those that are |
130 // locally hosted. | 99 // locally hosted. |
131 virtual void WriteRemoteCharacteristic( | 100 virtual void WriteRemoteCharacteristic( |
132 const std::vector<uint8_t>& new_value, | 101 const std::vector<uint8_t>& new_value, |
133 const base::Closure& callback, | 102 const base::Closure& callback, |
134 const ErrorCallback& error_callback) = 0; | 103 const ErrorCallback& error_callback) = 0; |
135 | 104 |
136 protected: | 105 protected: |
137 BluetoothRemoteGattCharacteristic(); | 106 BluetoothRemoteGattCharacteristic(); |
138 ~BluetoothRemoteGattCharacteristic() override; | 107 ~BluetoothRemoteGattCharacteristic() override; |
139 | 108 |
140 // Writes to the Client Characteristic Configuration descriptor to enable | |
141 // notifications/indications. This method is meant to be called from | |
142 // StartNotifySession and should contain only the code necessary to start | |
143 // listening to characteristic notifications on a particular platform. | |
144 virtual void SubscribeToNotifications( | |
145 BluetoothRemoteGattDescriptor* ccc_descriptor, | |
146 const base::Closure& callback, | |
147 const ErrorCallback& error_callback) = 0; | |
148 | |
149 // Writes to the Client Characteristic Configuration descriptor to disable | |
150 // notifications/indications. This method is meant to be called from | |
151 // StopNotifySession and should contain only the code necessary to stop | |
152 // listening to characteristic notifications on a particular platform. | |
153 virtual void UnsubscribeFromNotifications( | |
154 BluetoothRemoteGattDescriptor* ccc_descriptor, | |
155 const base::Closure& callback, | |
156 const ErrorCallback& error_callback) = 0; | |
157 | |
158 private: | 109 private: |
159 friend class BluetoothGattNotifySession; | |
160 | |
161 // Stops an active notify session for the remote characteristic. On success, | |
162 // the characteristic removes this session from the list of active sessions. | |
163 // If there are no more active sessions, notifications/indications are | |
164 // turned off. | |
165 // | |
166 // This method is, and should only be, called from | |
167 // BluetoothGattNotifySession::Stop(). | |
168 // | |
169 // The code in UnsubscribeFromNotifications writes to the Client | |
170 // Characteristic Configuration descriptor to disable | |
171 // notifications/indications. Core Bluetooth Specification [V4.2 Vol 3 Part G | |
172 // Section 3.3.1.1. Characteristic Properties] requires this descriptor to be | |
173 // present when notifications/indications are supported. | |
174 virtual void StopNotifySession(BluetoothGattNotifySession* session, | |
175 const base::Closure& callback); | |
176 | |
177 class NotifySessionCommand { | |
178 public: | |
179 enum Type { COMMAND_NONE, COMMAND_START, COMMAND_STOP }; | |
180 enum Result { RESULT_SUCCESS, RESULT_ERROR }; | |
181 | |
182 typedef base::Callback< | |
183 void(Type, Result, BluetoothRemoteGattService::GattErrorCode)> | |
184 ExecuteCallback; | |
185 | |
186 ExecuteCallback execute_callback_; | |
187 base::Closure cancel_callback_; | |
188 | |
189 NotifySessionCommand(const ExecuteCallback& execute_callback, | |
190 const base::Closure& cancel_callback); | |
191 ~NotifySessionCommand(); | |
192 | |
193 void Execute(); | |
194 void Execute( | |
195 Type previous_command_type, | |
196 Result previous_command_result, | |
197 BluetoothRemoteGattService::GattErrorCode previous_command_error_code); | |
198 void Cancel(); | |
199 }; | |
200 | |
201 void ExecuteStartNotifySession( | |
202 NotifySessionCallback callback, | |
203 ErrorCallback error_callback, | |
204 NotifySessionCommand::Type previous_command_type, | |
205 NotifySessionCommand::Result previous_command_result, | |
206 BluetoothRemoteGattService::GattErrorCode previous_command_error_code); | |
207 void CancelStartNotifySession(base::Closure callback); | |
208 void OnStartNotifySessionSuccess(NotifySessionCallback callback); | |
209 void OnStartNotifySessionError( | |
210 ErrorCallback error_callback, | |
211 BluetoothRemoteGattService::GattErrorCode error); | |
212 | |
213 void ExecuteStopNotifySession( | |
214 BluetoothGattNotifySession* session, | |
215 base::Closure callback, | |
216 NotifySessionCommand::Type previous_command_type, | |
217 NotifySessionCommand::Result previous_command_result, | |
218 BluetoothRemoteGattService::GattErrorCode previous_command_error_code); | |
219 void CancelStopNotifySession(base::Closure callback); | |
220 void OnStopNotifySessionSuccess(BluetoothGattNotifySession* session, | |
221 base::Closure callback); | |
222 void OnStopNotifySessionError( | |
223 BluetoothGattNotifySession* session, | |
224 base::Closure callback, | |
225 BluetoothRemoteGattService::GattErrorCode error); | |
226 | |
227 // Pending StartNotifySession / StopNotifySession calls. | |
228 std::queue<std::unique_ptr<NotifySessionCommand>> pending_notify_commands_; | |
229 | |
230 // Set of active notify sessions. | |
231 std::set<BluetoothGattNotifySession*> notify_sessions_; | |
232 | |
233 base::WeakPtrFactory<BluetoothRemoteGattCharacteristic> weak_ptr_factory_; | |
234 | |
235 DISALLOW_COPY_AND_ASSIGN(BluetoothRemoteGattCharacteristic); | 110 DISALLOW_COPY_AND_ASSIGN(BluetoothRemoteGattCharacteristic); |
236 }; | 111 }; |
237 | 112 |
238 } // namespace device | 113 } // namespace device |
239 | 114 |
240 #endif // DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ | 115 #endif // DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ |
OLD | NEW |