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> | |
9 #include <string> | 12 #include <string> |
10 #include <vector> | 13 #include <vector> |
11 | 14 |
12 #include "base/callback.h" | 15 #include "base/callback.h" |
13 #include "base/callback_forward.h" | 16 #include "base/callback_forward.h" |
14 #include "base/macros.h" | 17 #include "base/macros.h" |
18 #include "base/memory/weak_ptr.h" | |
15 #include "device/bluetooth/bluetooth_export.h" | 19 #include "device/bluetooth/bluetooth_export.h" |
16 #include "device/bluetooth/bluetooth_gatt_characteristic.h" | 20 #include "device/bluetooth/bluetooth_gatt_characteristic.h" |
21 #include "device/bluetooth/bluetooth_remote_gatt_service.h" | |
17 #include "device/bluetooth/bluetooth_uuid.h" | 22 #include "device/bluetooth/bluetooth_uuid.h" |
18 | 23 |
19 namespace device { | 24 namespace device { |
20 | 25 |
21 class BluetoothGattNotifySession; | 26 class BluetoothGattNotifySession; |
22 class BluetoothRemoteGattDescriptor; | 27 class BluetoothRemoteGattDescriptor; |
23 class BluetoothRemoteGattService; | 28 class BluetoothRemoteGattService; |
24 | 29 |
25 // BluetoothRemoteGattCharacteristic represents a remote GATT characteristic. | 30 // BluetoothRemoteGattCharacteristic represents a remote GATT characteristic. |
26 // This class is used to represent GATT characteristics that belong to a service | 31 // This class is used to represent GATT characteristics that belong to a service |
(...skipping 18 matching lines...) Expand all Loading... | |
45 NotifySessionCallback; | 50 NotifySessionCallback; |
46 | 51 |
47 // Returns the value of the characteristic. For remote characteristics, this | 52 // Returns the value of the characteristic. For remote characteristics, this |
48 // is the most recently cached value. For local characteristics, this is the | 53 // is the most recently cached value. For local characteristics, this is the |
49 // most recently updated value or the value retrieved from the delegate. | 54 // most recently updated value or the value retrieved from the delegate. |
50 virtual const std::vector<uint8_t>& GetValue() const = 0; | 55 virtual const std::vector<uint8_t>& GetValue() const = 0; |
51 | 56 |
52 // Returns a pointer to the GATT service this characteristic belongs to. | 57 // Returns a pointer to the GATT service this characteristic belongs to. |
53 virtual BluetoothRemoteGattService* GetService() const = 0; | 58 virtual BluetoothRemoteGattService* GetService() const = 0; |
54 | 59 |
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 | |
59 // Returns the list of GATT characteristic descriptors that provide more | 60 // Returns the list of GATT characteristic descriptors that provide more |
60 // information about this characteristic. | 61 // information about this characteristic. |
61 virtual std::vector<BluetoothRemoteGattDescriptor*> GetDescriptors() | 62 virtual std::vector<BluetoothRemoteGattDescriptor*> GetDescriptors() |
62 const = 0; | 63 const = 0; |
63 | 64 |
64 // Returns the GATT characteristic descriptor with identifier |identifier| if | 65 // Returns the GATT characteristic descriptor with identifier |identifier| if |
65 // it belongs to this GATT characteristic. | 66 // it belongs to this GATT characteristic. |
66 virtual BluetoothRemoteGattDescriptor* GetDescriptor( | 67 virtual BluetoothRemoteGattDescriptor* GetDescriptor( |
67 const std::string& identifier) const = 0; | 68 const std::string& identifier) const = 0; |
68 | 69 |
69 // Returns the GATT characteristic descriptors that match |uuid|. There may be | 70 // Returns the GATT characteristic descriptors that match |uuid|. There may be |
70 // multiple, as illustrated by Core Bluetooth Specification [V4.2 Vol 3 Part G | 71 // multiple, as illustrated by Core Bluetooth Specification [V4.2 Vol 3 Part G |
71 // 3.3.3.5 Characteristic Presentation Format]. | 72 // 3.3.3.5 Characteristic Presentation Format]. |
72 std::vector<BluetoothRemoteGattDescriptor*> GetDescriptorsByUUID( | 73 std::vector<BluetoothRemoteGattDescriptor*> GetDescriptorsByUUID( |
73 const BluetoothUUID& uuid); | 74 const BluetoothUUID& uuid) const; |
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; | |
74 | 89 |
75 // Starts a notify session for the remote characteristic, if it supports | 90 // Starts a notify session for the remote characteristic, if it supports |
76 // notifications/indications. On success, the characteristic starts sending | 91 // notifications/indications. On success, the characteristic starts sending |
77 // value notifications and |callback| is called with a session object whose | 92 // value notifications and |callback| is called with a session object whose |
78 // ownership belongs to the caller. |error_callback| is called on errors. | 93 // ownership belongs to the caller. |error_callback| is called on errors. |
79 // | 94 // |
80 // Writes to the Client Characteristic Configuration descriptor to enable | 95 // This method handles all logic regarding multiple sessions so that |
81 // notifications/indications. Core Bluetooth Specification [V4.2 Vol 3 Part G | 96 // specific platform implementations of the remote characteristic class |
82 // Section 3.3.1.1. Characteristic Properties] requires this descriptor to be | 97 // do not have to. Rather than overriding this method, it is recommended |
83 // present when notifications/indications are supported. If the descriptor is | 98 // to override the SubscribeToNotifications method below. |
84 // not present |error_callback| will be run. | 99 // |
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|. | |
85 virtual void StartNotifySession(const NotifySessionCallback& callback, | 116 virtual void StartNotifySession(const NotifySessionCallback& callback, |
86 const ErrorCallback& error_callback) = 0; | 117 const ErrorCallback& error_callback); |
87 | 118 |
88 // Sends a read request to a remote characteristic to read its value. | 119 // Sends a read request to a remote characteristic to read its value. |
89 // |callback| is called to return the read value on success and | 120 // |callback| is called to return the read value on success and |
90 // |error_callback| is called for failures. | 121 // |error_callback| is called for failures. |
91 virtual void ReadRemoteCharacteristic( | 122 virtual void ReadRemoteCharacteristic( |
92 const ValueCallback& callback, | 123 const ValueCallback& callback, |
93 const ErrorCallback& error_callback) = 0; | 124 const ErrorCallback& error_callback) = 0; |
94 | 125 |
95 // Sends a write request to a remote characteristic, to modify the | 126 // Sends a write request to a remote characteristic, to modify the |
96 // characteristic's value with the new value |new_value|. |callback| is | 127 // characteristic's value with the new value |new_value|. |callback| is |
97 // called to signal success and |error_callback| for failures. This method | 128 // called to signal success and |error_callback| for failures. This method |
98 // only applies to remote characteristics and will fail for those that are | 129 // only applies to remote characteristics and will fail for those that are |
99 // locally hosted. | 130 // locally hosted. |
100 virtual void WriteRemoteCharacteristic( | 131 virtual void WriteRemoteCharacteristic( |
101 const std::vector<uint8_t>& new_value, | 132 const std::vector<uint8_t>& new_value, |
102 const base::Closure& callback, | 133 const base::Closure& callback, |
103 const ErrorCallback& error_callback) = 0; | 134 const ErrorCallback& error_callback) = 0; |
104 | 135 |
105 protected: | 136 protected: |
106 BluetoothRemoteGattCharacteristic(); | 137 BluetoothRemoteGattCharacteristic(); |
107 ~BluetoothRemoteGattCharacteristic() override; | 138 ~BluetoothRemoteGattCharacteristic() override; |
108 | 139 |
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 | |
109 private: | 158 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 base::Closure execute_callback_; | |
183 base::Closure cancel_callback_; | |
184 | |
185 NotifySessionCommand(const base::Closure& execute_callback, | |
186 const base::Closure& cancel_callback); | |
187 ~NotifySessionCommand(); | |
188 | |
189 void Execute(); | |
190 void Cancel(); | |
191 }; | |
192 | |
193 void ExecuteStartNotifySession(NotifySessionCallback callback, | |
194 ErrorCallback error_callback); | |
195 void CancelStartNotifySession(base::Closure callback); | |
196 void StartNotifySessionSuccess(NotifySessionCallback callback); | |
ortuno
2016/08/09 21:57:56
nit: OnStartNotifySessionSuccess maybe? Same for t
tommyt
2016/08/10 12:07:19
Done.
| |
197 void StartNotifySessionError(ErrorCallback error_callback, | |
198 BluetoothRemoteGattService::GattErrorCode error); | |
199 | |
200 void ExecuteStopNotifySession(BluetoothGattNotifySession* session, | |
201 base::Closure callback); | |
202 void CancelStopNotifySession(base::Closure callback); | |
203 void StopNotifySessionSuccess(BluetoothGattNotifySession* session, | |
204 base::Closure callback); | |
205 void StopNotifySessionError(BluetoothGattNotifySession* session, | |
206 base::Closure callback, | |
207 BluetoothRemoteGattService::GattErrorCode error); | |
208 | |
209 // Pending StartNotifySession / StopNotifySession calls. | |
210 std::queue<std::unique_ptr<NotifySessionCommand>> pending_notify_commands_; | |
211 NotifySessionCommand::Type previous_command_type_ = | |
212 NotifySessionCommand::COMMAND_NONE; | |
213 NotifySessionCommand::Result previous_command_result_; | |
214 BluetoothRemoteGattService::GattErrorCode previous_command_error_code_; | |
215 | |
216 // Set of active notify sessions. | |
217 std::set<BluetoothGattNotifySession*> notify_sessions_; | |
218 | |
219 base::WeakPtrFactory<BluetoothRemoteGattCharacteristic> weak_ptr_factory_; | |
220 | |
110 DISALLOW_COPY_AND_ASSIGN(BluetoothRemoteGattCharacteristic); | 221 DISALLOW_COPY_AND_ASSIGN(BluetoothRemoteGattCharacteristic); |
111 }; | 222 }; |
112 | 223 |
113 } // namespace device | 224 } // namespace device |
114 | 225 |
115 #endif // DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ | 226 #endif // DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ |
OLD | NEW |