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