Direct-BT v3.3.0-1-gc2d430c
Direct-BT - Direct Bluetooth Programming.
BTGattDesc.hpp
Go to the documentation of this file.
1/*
2 * Author: Sven Gothel <sgothel@jausoft.com>
3 * Copyright (c) 2020 Gothel Software e.K.
4 * Copyright (c) 2020 ZAFENA AB
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining
7 * a copy of this software and associated documentation files (the
8 * "Software"), to deal in the Software without restriction, including
9 * without limitation the rights to use, copy, modify, merge, publish,
10 * distribute, sublicense, and/or sell copies of the Software, and to
11 * permit persons to whom the Software is furnished to do so, subject to
12 * the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be
15 * included in all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 */
25
26#ifndef BT_GATT_DESCRIPTOR_HPP_
27#define BT_GATT_DESCRIPTOR_HPP_
28
29#include <jau/octets.hpp>
30#include <jau/uuid.hpp>
31#include <cstring>
32#include <string>
33#include <memory>
34#include <cstdint>
35
36#include <mutex>
37#include <atomic>
38
39#include "BTTypes0.hpp"
40#include "ATTPDUTypes.hpp"
41
42#include "BTTypes1.hpp"
43
44/**
45 * - - - - - - - - - - - - - - -
46 *
47 * Module GATTDescriptor:
48 *
49 * - BT Core Spec v5.2: Vol 3, Part G Generic Attribute Protocol (GATT)
50 * - BT Core Spec v5.2: Vol 3, Part G GATT: 2.6 GATT Profile Hierarchy
51 */
52namespace direct_bt {
53
54 class BTDevice; // forward
55 class BTGattHandler; // forward
56 class BTGattChar; // forward
57 typedef std::shared_ptr<BTGattChar> BTGattCharRef;
58
59 /** \addtogroup DBTUserClientAPI
60 *
61 * @{
62 */
63
64 /**
65 * Representing a Gatt Characteristic Descriptor object from the ::GATTRole::Client perspective.
66 *
67 * A list of shared BTGattDesc instances is available from BTGattChar
68 * via BTGattChar::descriptorList.
69 *
70 * See [Direct-BT Overview](namespacedirect__bt.html#details).
71 *
72 * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3 Characteristic Descriptor
73 */
74 class BTGattDesc : public BTObject {
75 private:
76 /** Descriptor's characteristic weak back-reference */
77 std::weak_ptr<BTGattChar> wbr_char;
78
79 std::string toShortString() const noexcept;
80
81 public:
82 static const std::shared_ptr<jau::uuid_t> TYPE_EXT_PROP;
83 static const std::shared_ptr<jau::uuid_t> TYPE_USER_DESC;
84 static const std::shared_ptr<jau::uuid_t> TYPE_CCC_DESC;
85
86 /**
87 * Following UUID16 GATT profile attribute types are listed under:
88 * BT Core Spec v5.2: Vol 3, Part G GATT: 3.4 Summary of GATT Profile Attribute Types
89 *
90 * See GattAttributeType for further non BTGattDesc related declarations.
91 */
92 enum Type : uint16_t {
93 /* BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.1 Characteristic Extended Properties */
95 /* BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.2 Characteristic User Description (Characteristic Descriptor, optional, single, string) */
97 /* BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration (Characteristic Descriptor, optional, single, uint16_t bitfield) */
99 /* BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.4 Server Characteristic Configuration (Characteristic Descriptor, optional, single, bitfield) */
101 /* BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.5 Characteristic Presentation Format (Characteristic Descriptor, optional, single, complex) */
104
105 /** Our identifier to mark a custom vendor Characteristic Descriptor */
107 };
108
109 /** Type of descriptor */
110 std::unique_ptr<const jau::uuid_t> type;
111
112 /**
113 * Characteristic Descriptor Handle
114 * <p>
115 * Attribute handles are unique for each device (server) (BT Core Spec v5.2: Vol 3, Part F Protocol..: 3.2.2 Attribute Handle).
116 * </p>
117 */
118 const uint16_t handle;
119
120 /* Characteristics Descriptor's Value */
122
123 BTGattDesc(const BTGattCharRef & characteristic, std::unique_ptr<const jau::uuid_t> && type_,
124 const uint16_t handle_) noexcept
125 : wbr_char(characteristic), type(std::move(type_)), handle(handle_),
126 value(jau::lb_endian_t::little /* intentional zero sized */)
127 { }
128
129 std::string get_java_class() const noexcept override {
130 return java_class();
131 }
132 static std::string java_class() noexcept {
133 return std::string(JAVA_DBT_PACKAGE "DBTGattDesc");
134 }
135
136 std::shared_ptr<BTGattChar> getGattCharUnchecked() const noexcept { return wbr_char.lock(); }
137 std::shared_ptr<BTGattChar> getGattCharChecked() const;
138 std::shared_ptr<BTGattHandler> getGattHandlerUnchecked() const noexcept;
139 std::shared_ptr<BTDevice> getDeviceUnchecked() const noexcept;
140
141 std::string toString() const noexcept override;
142
143 /** Value is uint16_t bitfield */
144 bool isExtendedProperties() const noexcept { return *TYPE_EXT_PROP == *type; }
145
146 /* BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration (Characteristic Descriptor, optional, single, uint16_t bitfield) */
147 bool isClientCharConfig() const noexcept{ return *TYPE_CCC_DESC == *type; }
148
149 /* BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.2 Characteristic User Description */
150 bool isUserDescription() const noexcept{ return *TYPE_USER_DESC == *type; }
151
152 /**
153 * BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.1 Read Characteristic Descriptor
154 * <p>
155 * BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.2 Read Long Characteristic Descriptor
156 * </p>
157 * <p>
158 * If expectedLength = 0, then only one ATT_READ_REQ/RSP will be used.
159 * </p>
160 * <p>
161 * If expectedLength < 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used until
162 * the response returns zero. This is the default parameter.
163 * </p>
164 * <p>
165 * If expectedLength > 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used
166 * if required until the response returns zero.
167 * </p>
168 * <p>
169 * Convenience delegation call to BTGattHandler via BTDevice
170 * If the BTDevice's BTGattHandler is null, i.e. not connected, false is returned.
171 * </p>
172 */
173 bool readValue(int expectedLength=-1) noexcept;
174
175 /**
176 * BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.3 Write Characteristic Descriptors
177 * <p>
178 * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3 Characteristic Descriptor
179 * </p>
180 * <p>
181 * BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration
182 * </p>
183 * <p>
184 * Convenience delegation call to BTGattHandler via BTDevice
185 * If the BTDevice's BTGattHandler is null, i.e. not connected, false is returned.
186 * </p>
187 */
188 bool writeValue() noexcept;
189 };
190 typedef std::shared_ptr<BTGattDesc> BTGattDescRef;
191
192 inline bool operator==(const BTGattDesc& lhs, const BTGattDesc& rhs) noexcept
193 { return lhs.handle == rhs.handle; /** unique attribute handles */ }
194
195 inline bool operator!=(const BTGattDesc& lhs, const BTGattDesc& rhs) noexcept
196 { return !(lhs == rhs); }
197
198 /**@}*/
199
200} // namespace direct_bt
201
202#endif /* BT_GATT_DESCRIPTOR_HPP_ */
#define JAVA_DBT_PACKAGE
Definition: BTTypes0.hpp:43
BTDevice represents one remote Bluetooth device.
Definition: BTDevice.hpp:81
Representing a Gatt Characteristic Descriptor object from the GATTRole::Client perspective.
Definition: BTGattDesc.hpp:74
bool writeValue() noexcept
BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.3 Write Characteristic Descriptors.
Definition: BTGattDesc.cpp:85
BTGattDesc(const BTGattCharRef &characteristic, std::unique_ptr< const jau::uuid_t > &&type_, const uint16_t handle_) noexcept
Definition: BTGattDesc.hpp:123
const uint16_t handle
Characteristic Descriptor Handle.
Definition: BTGattDesc.hpp:118
std::shared_ptr< BTGattChar > getGattCharUnchecked() const noexcept
Definition: BTGattDesc.hpp:136
bool isClientCharConfig() const noexcept
Definition: BTGattDesc.hpp:147
static const std::shared_ptr< jau::uuid_t > TYPE_CCC_DESC
Definition: BTGattDesc.hpp:84
std::unique_ptr< const jau::uuid_t > type
Type of descriptor.
Definition: BTGattDesc.hpp:110
Type
Following UUID16 GATT profile attribute types are listed under: BT Core Spec v5.2: Vol 3,...
Definition: BTGattDesc.hpp:92
@ CUSTOM_CHARACTERISTIC_DESCRIPTION
Our identifier to mark a custom vendor Characteristic Descriptor.
Definition: BTGattDesc.hpp:106
bool readValue(int expectedLength=-1) noexcept
BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.1 Read Characteristic Descriptor.
Definition: BTGattDesc.cpp:71
std::string toString() const noexcept override
Definition: BTGattDesc.cpp:99
bool isUserDescription() const noexcept
Definition: BTGattDesc.hpp:150
bool isExtendedProperties() const noexcept
Value is uint16_t bitfield.
Definition: BTGattDesc.hpp:144
std::string get_java_class() const noexcept override
Definition: BTGattDesc.hpp:129
std::shared_ptr< BTGattChar > getGattCharChecked() const
Definition: BTGattDesc.cpp:47
static const std::shared_ptr< jau::uuid_t > TYPE_USER_DESC
Definition: BTGattDesc.hpp:83
static const std::shared_ptr< jau::uuid_t > TYPE_EXT_PROP
Definition: BTGattDesc.hpp:82
std::shared_ptr< BTGattHandler > getGattHandlerUnchecked() const noexcept
Definition: BTGattDesc.cpp:55
static std::string java_class() noexcept
Definition: BTGattDesc.hpp:132
std::shared_ptr< BTDevice > getDeviceUnchecked() const noexcept
Definition: BTGattDesc.cpp:63
Persistent endian aware octet data, i.e.
Definition: octets.hpp:560
@ little
Identifier for little endian, equivalent to endian::little.
bool operator!=(const BTAdapter &lhs, const BTAdapter &rhs) noexcept
Definition: BTAdapter.hpp:1351
std::shared_ptr< BTGattChar > BTGattCharRef
Definition: BTGattChar.hpp:410
std::shared_ptr< BTGattDesc > BTGattDescRef
Definition: BTGattDesc.hpp:190
STL namespace.