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 3 // found in the LICENSE file. 4 5 #ifndef DEVICE_BLUETOOTH_BLUETOOTH_GATT_SERVICE_H_ 6 #define DEVICE_BLUETOOTH_BLUETOOTH_GATT_SERVICE_H_ 7 8 #include <vector> 9 10 #include "base/basictypes.h" 11 #include "base/callback.h" 12 #include "device/bluetooth/bluetooth_uuid.h" 13 14 namespace device { 15 16 class BluetoothDevice; 17 class BluetoothGattCharacteristic; 18 class BluetoothGattDescriptor; 19 20 // BluetoothGattService represents a local or remote GATT service. A GATT 21 // service is hosted by a peripheral and represents a collection of data in 22 // the form of GATT characteristics and a set of included GATT services if this 23 // service is what is called "a primary service". 24 // 25 // Instances of the BluetoothGattService class are used for two functions: 26 // 1. To represent GATT attribute hierarchies that have been received from a 27 // remote Bluetooth GATT peripheral. Such BluetoothGattService instances 28 // are constructed and owned by a BluetoothDevice. 29 // 30 // 2. To represent a locally hosted GATT attribute hierarchy when the local 31 // adapter is used in the "peripheral" role. Such instances are meant to be 32 // constructed directly and registered. Once registered, a GATT attribute 33 // hierarchy will be visible to remote devices in the "central" role. 34 class BluetoothGattService { 35 public: 36 // The Delegate class is used to send certain events that need to be handled 37 // when the device is in peripheral mode. The delegate handles read and write 38 // requests that are issued from remote clients. 39 class Delegate { 40 public: 41 // Callbacks used for communicating GATT request responses. 42 typedef base::Callback<void(const std::vector<uint8>)> ValueCallback; 43 typedef base::Closure ErrorCallback; 44 45 // Called when a remote device in the central role requests to read the 46 // value of the characteristic |characteristic| starting at offset |offset|. 47 // This method is only called if the characteristic was specified as 48 // readable and any authentication and authorization challanges were 49 // satisfied by the remote device. 50 // 51 // To respond to the request with success and return the requested value, 52 // the delegate must invoke |callback| with the value. Doing so will 53 // automatically update the value property of |characteristic|. To respond 54 // to the request with failure (e.g. if an invalid offset was given), 55 // delegates must invoke |error_callback|. If neither callback parameter is 56 // invoked, the request will time out and result in an error. Therefore, 57 // delegates MUST invoke either |callback| or |error_callback|. 58 virtual void OnCharacteristicReadRequest( 59 const BluetoothGattService* service, 60 const BluetoothGattCharacteristic* characteristic, 61 int offset, 62 const ValueCallback& callback, 63 const ErrorCallback& error_callback) = 0; 64 65 // Called when a remote device in the central role requests to write the 66 // value of the characteristic |characteristic| starting at offset |offset|. 67 // This method is only called if the characteristic was specified as 68 // writeable and any authentication and authorization challanges were 69 // satisfied by the remote device. 70 // 71 // To respond to the request with success the delegate must invoke 72 // |callback| with the new value of the characteristic. Doing so will 73 // automatically update the value property of |characteristic|. To respond 74 // to the request with failure (e.g. if an invalid offset was given), 75 // delegates must invoke |error_callback|. If neither callback parameter is 76 // invoked, the request will time out and result in an error. Therefore, 77 // delegates MUST invoke either |callback| or |error_callback|. 78 virtual void OnCharacteristicWriteRequest( 79 const BluetoothGattService* service, 80 const BluetoothGattCharacteristic* characteristic, 81 const std::vector<uint8>& value, 82 int offset, 83 const ValueCallback& callback, 84 const ErrorCallback& error_callback) = 0; 85 86 // Called when a remote device in the central role requests to read the 87 // value of the descriptor |descriptor| starting at offset |offset|. 88 // This method is only called if the characteristic was specified as 89 // readable and any authentication and authorization challanges were 90 // satisfied by the remote device. 91 // 92 // To respond to the request with success and return the requested value, 93 // the delegate must invoke |callback| with the value. Doing so will 94 // automatically update the value property of |descriptor|. To respond 95 // to the request with failure (e.g. if an invalid offset was given), 96 // delegates must invoke |error_callback|. If neither callback parameter is 97 // invoked, the request will time out and result in an error. Therefore, 98 // delegates MUST invoke either |callback| or |error_callback|. 99 virtual void OnDescriptorReadRequest( 100 const BluetoothGattService* service, 101 const BluetoothGattDescriptor* descriptor, 102 int offset, 103 const ValueCallback& callback, 104 const ErrorCallback& error_callback) = 0; 105 106 // Called when a remote device in the central role requests to write the 107 // value of the descriptor |descriptor| starting at offset |offset|. 108 // This method is only called if the characteristic was specified as 109 // writeable and any authentication and authorization challanges were 110 // satisfied by the remote device. 111 // 112 // To respond to the request with success the delegate must invoke 113 // |callback| with the new value of the descriptor. Doing so will 114 // automatically update the value property of |descriptor|. To respond 115 // to the request with failure (e.g. if an invalid offset was given), 116 // delegates must invoke |error_callback|. If neither callback parameter is 117 // invoked, the request will time out and result in an error. Therefore, 118 // delegates MUST invoke either |callback| or |error_callback|. 119 virtual void OnDescriptorWriteRequest( 120 const BluetoothGattService* service, 121 const BluetoothGattDescriptor* descriptor, 122 const std::vector<uint8>& value, 123 int offset, 124 const ValueCallback& callback, 125 const ErrorCallback& error_callback) = 0; 126 }; 127 128 // Interface for observing changes from a BluetoothGattService. Properties 129 // of remote services are received asynchronously. The Observer interface can 130 // be used to be notified when the initial values of a service are received 131 // as well as when successive changes occur during its life cycle. 132 class Observer { 133 public: 134 // Called when properties of the remote GATT service |service| have changed. 135 // This will get called for properties such as UUID, as well as for changes 136 // to the list of known characteristics and included services. Observers 137 // should read all GATT characteristic and descriptors objects and do any 138 // necessary set up required for a changed service. This method may be 139 // called several times, especially when the service is discovered for the 140 // first time. It will be called for each characteristic and characteristic 141 // descriptor that is discovered or removed. Hence this method should be 142 // used to check whether or not all characteristics of a service have been 143 // discovered that correspond to the profile implemented by the Observer. 144 virtual void GattServiceChanged(BluetoothGattService* service) {} 145 146 // Called when the remote GATT characteristic |characteristic| belonging to 147 // GATT service |service| has been discovered. Use this to issue any initial 148 // read/write requests to the characteristic but don't cache the pointer as 149 // it may become invalid. Instead, use the specially assigned identifier 150 // to obtain a characteristic and cache that identifier as necessary, as it 151 // can be used to retrieve the characteristic from its GATT service. The 152 // number of characteristics with the same UUID belonging to a service 153 // depends on the particular profile the remote device implements, hence the 154 // client of a GATT based profile will usually operate on the whole set of 155 // characteristics and not just one. 156 // 157 // This method will always be followed by a call to GattServiceChanged, 158 // which can be used by observers to get all the characteristics of a 159 // service and perform the necessary updates. GattCharacteristicAdded exists 160 // mostly for convenience. 161 virtual void GattCharacteristicAdded( 162 BluetoothGattService* service, 163 BluetoothGattCharacteristic* characteristic) {} 164 165 // Called when a GATT characteristic |characteristic| belonging to GATT 166 // service |service| has been removed. This method is for convenience 167 // and will be followed by a call to GattServiceChanged (except when called 168 // after the service gets removed) which should be used for bootstrapping a 169 // GATT based profile. See the documentation of GattCharacteristicAdded and 170 // GattServiceChanged for more information. Try to obtain the service from 171 // its device to see whether or not the service has been removed. 172 virtual void GattCharacteristicRemoved( 173 BluetoothGattService* service, 174 BluetoothGattCharacteristic* characteristic) {} 175 176 // Called when the remote GATT characteristic descriptor |descriptor| 177 // belonging to characteristic |characteristic| has been discovered. Don't 178 // cache the arguments as the pointers may become invalid. Instead, use the 179 // specially assigned identifier to obtain a descriptor and cache that 180 // identifier as necessary. 181 // 182 // This method will always be followed by a call to GattServiceChanged, 183 // which can be used by observers to get all the characteristics of a 184 // service and perform the necessary updates. GattDescriptorAdded exists 185 // mostly for convenience. 186 virtual void GattDescriptorAdded( 187 BluetoothGattCharacteristic* characteristic, 188 BluetoothGattDescriptor* descriptor) {} 189 190 // Called when a GATT characteristic descriptor |descriptor| belonging to 191 // characteristic |characteristic| has been removed. This method is for 192 // convenience and will be followed by a call to GattServiceChanged (except 193 // when called after the service gets removed). 194 virtual void GattDescriptorRemoved( 195 BluetoothGattCharacteristic* characteristic, 196 BluetoothGattDescriptor* descriptor) {} 197 198 // Called when the value of a characteristic has changed. This might be a 199 // result of a read/write request to, or a notification/indication from, a 200 // remote GATT characteristic. 201 virtual void GattCharacteristicValueChanged( 202 BluetoothGattService* service, 203 BluetoothGattCharacteristic* characteristic, 204 const std::vector<uint8>& value) {} 205 206 // Called when the value of a characteristic descriptor has been updated. 207 virtual void GattDescriptorValueChanged( 208 BluetoothGattCharacteristic* characteristic, 209 BluetoothGattDescriptor* descriptor, 210 const std::vector<uint8>& value) {} 211 }; 212 213 // The ErrorCallback is used by methods to asynchronously report errors. 214 typedef base::Closure ErrorCallback; 215 216 virtual ~BluetoothGattService(); 217 218 // Adds and removes observers for events on this GATT service. If monitoring 219 // multiple services, check the |service| parameter of observer methods to 220 // determine which service is issuing the event. 221 virtual void AddObserver(Observer* observer) = 0; 222 virtual void RemoveObserver(Observer* observer) = 0; 223 224 // Constructs a BluetoothGattService that can be locally hosted when the local 225 // adapter is in the peripheral role. The resulting object can then be made 226 // available by calling the "Register" method. This method constructs a 227 // service with UUID |uuid|. Whether the constructed service is primary or 228 // secondary is determined by |is_primary|. |delegate| is used to send certain 229 // peripheral role events. If |delegate| is NULL, then this service will 230 // employ a default behavior when responding to read and write requests based 231 // on the cached value of its characteristics and descriptors at a given time. 232 static BluetoothGattService* Create(const BluetoothUUID& uuid, 233 bool is_primary, 234 Delegate* delegate); 235 236 // Identifier used to uniquely identify a GATT service object. This is 237 // different from the service UUID: while multiple services with the same UUID 238 // can exist on a Bluetooth device, the identifier returned from this method 239 // is unique among all services of a device. The contents of the identifier 240 // are platform specific. 241 virtual std::string GetIdentifier() const = 0; 242 243 // The Bluetooth-specific UUID of the service. 244 virtual BluetoothUUID GetUUID() const = 0; 245 246 // Returns true, if this service hosted locally. If false, then this service 247 // represents a remote GATT service. 248 virtual bool IsLocal() const = 0; 249 250 // Indicates whether the type of this service is primary or secondary. A 251 // primary service describes the primary function of the peripheral that 252 // hosts it, while a secondary service only makes sense in the presence of a 253 // primary service. A primary service may include other primary or secondary 254 // services. 255 virtual bool IsPrimary() const = 0; 256 257 // Returns the BluetoothDevice that this GATT service was received from, which 258 // also owns this service. Local services always return NULL. 259 virtual BluetoothDevice* GetDevice() const = 0; 260 261 // List of characteristics that belong to this service. 262 virtual std::vector<BluetoothGattCharacteristic*> 263 GetCharacteristics() const = 0; 264 265 // List of GATT services that are included by this service. 266 virtual std::vector<BluetoothGattService*> 267 GetIncludedServices() const = 0; 268 269 // Returns the GATT characteristic with identifier |identifier| if it belongs 270 // to this GATT service. 271 virtual BluetoothGattCharacteristic* GetCharacteristic( 272 const std::string& identifier) const = 0; 273 274 // Adds characteristics and included services to the local attribute hierarchy 275 // represented by this service. These methods only make sense for local 276 // services and won't have an effect if this instance represents a remote 277 // GATT service and will return false. While ownership of added 278 // characteristics are taken over by the service, ownership of an included 279 // service is not taken. 280 virtual bool AddCharacteristic( 281 BluetoothGattCharacteristic* characteristic) = 0; 282 virtual bool AddIncludedService(BluetoothGattService* service) = 0; 283 284 // Registers this GATT service. Calling Register will make this service and 285 // all of its associated attributes available on the local adapters GATT 286 // database and the service UUID will be advertised to nearby devices if the 287 // local adapter is discoverable. Call Unregister to make this service no 288 // longer available. 289 // 290 // These methods only make sense for services that are local and will hence 291 // fail if this instance represents a remote GATT service. |callback| is 292 // called to denote success and |error_callback| to denote failure. 293 virtual void Register(const base::Closure& callback, 294 const ErrorCallback& error_callback) = 0; 295 virtual void Unregister(const base::Closure& callback, 296 const ErrorCallback& error_callback) = 0; 297 298 protected: 299 BluetoothGattService(); 300 301 private: 302 DISALLOW_COPY_AND_ASSIGN(BluetoothGattService); 303 }; 304 305 } // namespace device 306 307 #endif // DEVICE_BLUETOOTH_BLUETOOTH_GATT_SERVICE_H_ 308