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 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 |
110 DISALLOW_COPY_AND_ASSIGN(BluetoothRemoteGattCharacteristic); | 235 DISALLOW_COPY_AND_ASSIGN(BluetoothRemoteGattCharacteristic); |
111 }; | 236 }; |
112 | 237 |
113 } // namespace device | 238 } // namespace device |
114 | 239 |
115 #endif // DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ | 240 #endif // DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_CHARACTERISTIC_H_ |
OLD | NEW |