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_DESCRIPTOR_H_ 6 #define DEVICE_BLUETOOTH_BLUETOOTH_GATT_DESCRIPTOR_H_ 7 8 #include <vector> 9 10 #include "base/basictypes.h" 11 #include "base/callback.h" 12 #include "device/bluetooth/bluetooth_gatt_characteristic.h" 13 #include "device/bluetooth/bluetooth_uuid.h" 14 15 namespace device { 16 17 // BluetoothGattDescriptor represents a local or remote GATT characteristic 18 // descriptor. A GATT characteristic descriptor provides further information 19 // about a characteristic's value. They can be used to describe the 20 // characteristic's features or to control certain behaviors. 21 class BluetoothGattDescriptor { 22 public: 23 // The Bluetooth Specification declares several predefined descriptors that 24 // profiles can use. The following are definitions for the list of UUIDs 25 // and descriptions of the characteristic descriptors that they represent. 26 // Possible values for and further information on each descriptor can be found 27 // in Core v4.0, Volume 3, Part G, Section 3.3.3. All of these desciptors are 28 // optional and may not be present for a given characteristic. 29 30 // The "Characteristic Extended Properties" descriptor. This defines 31 // additional "Characteristic Properties" which cannot fit into the allocated 32 // single octet property field of a characteristic. The value is a bit field 33 // and the two predefined bits, as per Bluetooth Core Specification v4.0, are: 34 // 35 // - Reliable Write: 0x0001 36 // - Writable Auxiliaries: 0x0002 37 // 38 static const BluetoothUUID& CharacteristicExtendedPropertiesUuid(); 39 40 // The "Characteristic User Description" descriptor defines a UTF-8 string of 41 // variable size that is a user textual description of the associated 42 // characteristic's value. There can be only one instance of this descriptor 43 // per characteristic. This descriptor can be written to if the "Writable 44 // Auxiliaries" bit of the Characteristic Properties (via the "Characteristic 45 // Extended Properties" descriptor) has been set. 46 static const BluetoothUUID& CharacteristicUserDescriptionUuid(); 47 48 // The "Client Characteristic Configuration" descriptor defines how the 49 // characteristic may be configured by a specific client. A server-side 50 // instance of this descriptor exists for each client that has bonded with 51 // the server and the value can be read and written by that client only. As 52 // of Core v4.0, this descriptor is used by clients to set up notifications 53 // and indications from a characteristic. The value is a bit field and the 54 // predefined bits are: 55 // 56 // - Default: 0x0000 57 // - Notification: 0x0001 58 // - Indication: 0x0002 59 // 60 static const BluetoothUUID& ClientCharacteristicConfigurationUuid(); 61 62 // The "Server Characteristic Configuration" descriptor defines how the 63 // characteristic may be configured for the server. There is one instance 64 // of this descriptor for all clients and setting the value of this descriptor 65 // affects its configuration for all clients. As of Core v4.0, this descriptor 66 // is used to set up the server to broadcast the characteristic value if 67 // advertising resources are available. The value is a bit field and the 68 // predefined bits are: 69 // 70 // - Default: 0x0000 71 // - Broadcast: 0x0001 72 // 73 static const BluetoothUUID& ServerCharacteristicConfigurationUuid(); 74 75 // The "Characteristic Presentation Format" declaration defines the format of 76 // the Characteristic Value. The value is composed of 7 octets which are 77 // divided into groups that represent different semantic meanings. For a 78 // detailed description of how the value of this descriptor should be 79 // interpreted, refer to Core v4.0, Volume 3, Part G, Section 3.3.3.5. If more 80 // than one declaration of this descriptor exists for a characteristic, then a 81 // "Characteristic Aggregate Format" descriptor must also exist for that 82 // characteristic. 83 static const BluetoothUUID& CharacteristicPresentationFormatUuid(); 84 85 // The "Characteristic Aggregate Format" descriptor defines the format of an 86 // aggragated characteristic value. In GATT's underlying protocol, ATT, each 87 // attribute is identified by a handle that is unique for the hosting server. 88 // Multiple characteristics can share the same instance(s) of a 89 // "Characteristic Presentation Format" descriptor. The value of the 90 // "Characteristic Aggregate Format" descriptor contains a list of handles 91 // that each refer to a "Characteristic Presentation Format" descriptor that 92 // is used by that characteristic. Hence, exactly one instance of this 93 // descriptor must exist if more than one "Characteristic Presentation Format" 94 // descriptors exist for a characteristic. 95 // 96 // Applications that are using the device::Bluetooth API do not have access to 97 // the underlying handles and shouldn't use this descriptor to determine which 98 // "Characteristic Presentation Format" desciptors belong to a characteristic. 99 // The API will construct a BluetoothGattDescriptor object for each instance 100 // of "Characteristic Presentation Format" descriptor per instance of 101 // BluetoothGattCharacteristic that represents a remote characteristic. 102 // Similarly for local characteristics, implementations DO NOT need to create 103 // an instance of BluetoothGattDescriptor for this descriptor as this will be 104 // handled by the subsystem. 105 static const BluetoothUUID& CharacteristicAggregateFormatUuid(); 106 107 // The ErrorCallback is used by methods to asynchronously report errors. 108 typedef base::Closure ErrorCallback; 109 110 // The ValueCallback is used to return the value of a remote characteristic 111 // descriptor upon a read request. 112 typedef base::Callback<void(const std::vector<uint8>&)> ValueCallback; 113 114 // Constructs a BluetoothGattDescriptor that can be associated with a local 115 // GATT characteristic when the adapter is in the peripheral role. To 116 // associate the returned descriptor with a characteristic, add it to a local 117 // characteristic by calling BluetoothGattCharacteristic::AddDescriptor. 118 // 119 // This method constructs a characteristic descriptor with UUID |uuid| and the 120 // initial cached value |value|. |value| will be cached and returned for read 121 // requests and automatically modified for write requests by default, unless 122 // an instance of BluetoothGattService::Delegate has been provided to the 123 // associated BluetoothGattService instance, in which case the delegate will 124 // handle the read and write requests. 125 // 126 // Currently, only custom UUIDs, |kCharacteristicDescriptionUuid|, and 127 // |kCharacteristicPresentationFormat| are supported for locally hosted 128 // descriptors. This method will return NULL if |uuid| is any one of the 129 // unsupported predefined descriptor UUIDs. 130 static BluetoothGattDescriptor* Create( 131 const BluetoothUUID& uuid, 132 const std::vector<uint8>& value, 133 BluetoothGattCharacteristic::Permissions permissions); 134 135 // Identifier used to uniquely identify a GATT descriptorobject. This is 136 // different from the descriptor UUID: while multiple descriptors with the 137 // same UUID can exist on a Bluetooth device, the identifier returned from 138 // this method is unique among all descriptors of a device. The contents of 139 // the identifier are platform specific. 140 virtual std::string GetIdentifier() const = 0; 141 142 // The Bluetooth-specific UUID of the characteristic descriptor. 143 virtual BluetoothUUID GetUUID() const = 0; 144 145 // Returns true, if this characteristic descriptor is hosted locally. If 146 // false, then this instance represents a remote descriptor. 147 virtual bool IsLocal() const = 0; 148 149 // Returns the value of the descriptor. For remote descriptors, this is the 150 // most recently cached value of the remote descriptor. For local descriptors 151 // this is the most recently updated value or the value retrieved from the 152 // delegate. 153 virtual const std::vector<uint8>& GetValue() const = 0; 154 155 // Returns a pointer to the GATT characteristic that this characteristic 156 // descriptor belongs to. 157 virtual BluetoothGattCharacteristic* GetCharacteristic() const = 0; 158 159 // Returns the bitmask of characteristic descriptor attribute permissions. 160 virtual BluetoothGattCharacteristic::Permissions GetPermissions() const = 0; 161 162 // Sends a read request to a remote characteristic descriptor to read its 163 // value. |callback| is called to return the read value on success and 164 // |error_callback| is called for failures. 165 virtual void ReadRemoteDescriptor(const ValueCallback& callback, 166 const ErrorCallback& error_callback) = 0; 167 168 // Sends a write request to a remote characteristic descriptor, to modify the 169 // value of the descriptor with the new value |new_value|. |callback| is 170 // called to signal success and |error_callback| for failures. This method 171 // only applies to remote descriptors and will fail for those that are locally 172 // hosted. 173 virtual void WriteRemoteDescriptor( 174 const std::vector<uint8>& new_value, 175 const base::Closure& callback, 176 const ErrorCallback& error_callback) = 0; 177 178 protected: 179 BluetoothGattDescriptor(); 180 virtual ~BluetoothGattDescriptor(); 181 182 private: 183 DISALLOW_COPY_AND_ASSIGN(BluetoothGattDescriptor); 184 }; 185 186 } // namespace device 187 188 #endif // DEVICE_BLUETOOTH_BLUETOOTH_GATT_DESCRIPTOR_H_ 189
