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