Mistake on this page?
Report an issue in GitHub or email us
gatt/GattAttribute.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2020 ARM Limited
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 #ifndef MBED_GATT_ATTRIBUTE_H__
20 #define MBED_GATT_ATTRIBUTE_H__
21 
22 #include "ble/common/UUID.h"
23 #include "ble/common/BLETypes.h"
24 
25 /**
26  * @addtogroup ble
27  * @{
28  * @addtogroup gatt
29  * @{
30  * @addtogroup server
31  * @{
32  */
33 
34 /**
35  * Representation of a GattServer attribute.
36  *
37  * Attributes are the building block of GATT servers: services are attributes,
38  * characteristics are groups of attributes and characteristic descriptors are
39  * attributes, too.
40  *
41  * @par Typed values
42  *
43  * Attributes are typed values composed of a type and its associated value. The
44  * attribute type identifies the attribute purpose. A UUID read by the client
45  * during the discovery of the GATT server models the attribute type. The value of the
46  * attribute is an array of bytes; its length may be fixed or variable.
47  *
48  * As an example, a primary service is declared by an attribute with the type
49  * 0x2800, and the value of the attribute is the UUID of the service.
50  *
51  * @par Attribute Access
52  *
53  * The GATT server is an array of attributes in which a unique index identifies
54  * each of the attributes within the array. That index is called the attribute
55  * handle, and clients use it to access to attributes within the server.
56  *
57  * @note Attributes do not contain information related to their permissions,
58  * grouping or semantic. Higher level specifications define these concepts.
59  */
61 public:
62  /**
63  * Representation of an attribute handle.
64  *
65  * Each attribute in a GattServer has a unique handle that clients can use
66  * to identify the attribute. The underlying BLE stack usually
67  * generates and assigns handles to attributes.
68  */
70 
71  /**
72  * Invalid attribute handle.
73  */
74  static const Handle_t INVALID_HANDLE = 0x0000;
75 
76 public:
77 
79 
80  /**
81  * Construct an attribute.
82  *
83  * Application code uses attributes to model characteristic descriptors and
84  * characteristics values.
85  *
86  * @param[in] uuid The type of the attribute.
87  * @param[in] valuePtr Pointer to the memory buffer, which contains the
88  * initial value of the attribute. The constructor does not make a copy of
89  * the attribute buffer; as a consequence, the memory buffer must remain
90  * valid during the lifetime of the attribute.
91  * @param[in] len The length in bytes of this attribute's value.
92  * @param[in] maxLen The length in bytes of the memory buffer containing the
93  * attribute value. It must be greater than or equal to @p len.
94  * @param[in] hasVariableLen Flag that indicates whether the attribute's value
95  * length can change throughout time.
96  *
97  * @par Example
98  *
99  * @code
100  * // declare a value of 2 bytes within a 10 bytes buffer
101  * const uint8_t attribute_value[10] = { 10, 50 };
102  * GattAttribute attr = GattAttribute(
103  * 0x2A19, // attribute type
104  * attribute_value,
105  * 2, // length of the current value
106  * sizeof(attribute_value), // length of the buffer containing the value
107  * true // variable length
108  * );
109  * @endcode
110  *
111  * @note By default, read and write operations are allowed and does not
112  * require any security.
113  */
115  const UUID &uuid,
116  uint8_t *valuePtr = nullptr,
117  uint16_t len = 0,
118  uint16_t maxLen = 0,
119  bool hasVariableLen = true
120  ) : _uuid(uuid),
121  _valuePtr(valuePtr),
122  _lenMax(maxLen),
123  _len(len),
124  _handle(),
125  _hasVariableLen(hasVariableLen),
126  _read_allowed(true),
127  _read_security(Security_t::NONE),
128  _write_allowed(true),
129  _write_security(Security_t::NONE) {
130  }
131 
132  GattAttribute(const GattAttribute &) = delete;
133  GattAttribute& operator=(const GattAttribute &) = delete;
134 
135 public:
136  /**
137  * Get the attribute's handle in the ATT table.
138  *
139  * @note The GattServer sets the attribute's handle when services are
140  * inserted.
141  *
142  * @return The attribute's handle.
143  */
144  Handle_t getHandle() const
145  {
146  return _handle;
147  }
148 
149  /**
150  * Get the UUID of the attribute.
151  *
152  * The UUID identifies the type of the attribute.
153  *
154  * @return The attribute.
155  */
156  const UUID &getUUID() const
157  {
158  return _uuid;
159  }
160 
161  /**
162  * Get the current length of the attribute value.
163  *
164  * @return The current length of the attribute value.
165  */
166  uint16_t getLength() const
167  {
168  return _len;
169  }
170 
171  /**
172  * Get the maximum length of the attribute value.
173  *
174  * The maximum length of the attribute value.
175  */
176  uint16_t getMaxLength() const
177  {
178  return _lenMax;
179  }
180 
181  /**
182  * Get a pointer to the current length of the attribute value.
183  *
184  * @attention note Do not use this function.
185  *
186  * @return A pointer to the current length of the attribute value.
187  */
188  uint16_t *getLengthPtr()
189  {
190  return &_len;
191  }
192 
193  /**
194  * Set the attribute handle.
195  *
196  * @attention The GattServer uses this function internally.
197  * Application code must not use it.
198  *
199  * @param[in] id The new attribute handle.
200  */
201  void setHandle(Handle_t id)
202  {
203  _handle = id;
204  }
205 
206  /**
207  * Get a pointer to the attribute value.
208  *
209  * @return A pointer to the attribute value.
210  */
211  uint8_t *getValuePtr()
212  {
213  return _valuePtr;
214  }
215 
216  /**
217  * Check whether the length of the attribute's value can change throughout time.
218  *
219  * @return true if the attribute value has a variable length and false
220  * otherwise.
221  */
222  bool hasVariableLength() const
223  {
224  return _hasVariableLen;
225  }
226 
227  /**
228  * Allow or disallow read operation from a client.
229  * @param allow_read Read is allowed if true.
230  */
231  void allowRead(bool allow_read)
232  {
233  _read_allowed = allow_read;
234  }
235 
236  /**
237  * Indicate if a client is allowed to read the attribute.
238  * @return true if a client is allowed to read the attribute.
239  */
240  bool isReadAllowed() const
241  {
242  return _read_allowed;
243  }
244 
245  /**
246  * Set the security requirements of the read operations.
247  * @param requirement The security level required by the read operations.
248  */
249  void setReadSecurityRequirement(Security_t requirement)
250  {
251  _read_security = requirement.value();
252  }
253 
254  /**
255  * Return the security level required by read operations.
256  * @return The security level of the read operations.
257  */
258  Security_t getReadSecurityRequirement() const
259  {
260  return static_cast<Security_t::type>(_read_security);
261  }
262 
263  /**
264  * Allow or disallow write operation from a client.
265  * @param allow_write Write is allowed if true.
266  */
267  void allowWrite(bool allow_write)
268  {
269  _write_allowed = allow_write;
270  }
271 
272  /**
273  * Indicate if a client is allowed to write the attribute.
274  * @return true if a client is allowed to write the attribute.
275  */
276  bool isWriteAllowed() const
277  {
278  return _write_allowed;
279  }
280 
281  /**
282  * Set the security requirements of the write operations.
283  * @param requirement The security level required by the write operations.
284  */
285  void setWriteSecurityRequirement(Security_t requirement)
286  {
287  _write_security = requirement.value();
288  }
289 
290  /**
291  * Return the security level required by write operations.
292  * @return The security level of the write operations.
293  */
294  Security_t getWriteSecurityRequirement() const
295  {
296  return static_cast<Security_t::type>(_write_security);
297  }
298 
299 private:
300  /**
301  * Characteristic's UUID.
302  */
303  UUID _uuid;
304 
305  /**
306  * Pointer to the attribute's value.
307  */
308  uint8_t *_valuePtr;
309 
310  /**
311  * Length in byte of the buffer containing the attribute value.
312  */
313  uint16_t _lenMax;
314 
315  /**
316  * Current length of the value pointed to by GattAttribute::_valuePtr.
317  */
318  uint16_t _len;
319 
320  /**
321  * The attribute's handle in the ATT table.
322  */
323  Handle_t _handle;
324 
325  /**
326  * Whether the length of the value can change throughout time.
327  */
328  bool _hasVariableLen;
329 
330  /**
331  * Whether read is allowed or not.
332  */
333  uint8_t _read_allowed:1;
334 
335  /**
336  * Security applied to the read operation.
337  */
338  uint8_t _read_security: Security_t::size;
339 
340  /**
341  * Whether write is allowed or not.
342  */
343  uint8_t _write_allowed:1;
344 
345  /**
346  * Security applied to the write operation.
347  */
348  uint8_t _write_security: Security_t::size;
349 };
350 
351 /**
352  * @}
353  * @}
354  * @}
355  */
356 
357 #endif /* ifndef MBED_GATT_ATTRIBUTE_H__ */
void setReadSecurityRequirement(Security_t requirement)
Set the security requirements of the read operations.
void allowWrite(bool allow_write)
Allow or disallow write operation from a client.
Security_t getReadSecurityRequirement() const
Return the security level required by read operations.
Handle_t getHandle() const
Get the attribute&#39;s handle in the ATT table.
static const Handle_t INVALID_HANDLE
Invalid attribute handle.
Security requirement that can be attached to an attribute operation.
void allowRead(bool allow_read)
Allow or disallow read operation from a client.
const UUID & getUUID() const
Get the UUID of the attribute.
uint8_t * getValuePtr()
Get a pointer to the attribute value.
LayoutType value() const
Explicit access to the inner value of the SafeEnum instance.
uint16_t getMaxLength() const
Get the maximum length of the attribute value.
type
struct scoped enum wrapped by the class
void setHandle(Handle_t id)
Set the attribute handle.
Representation of a Universally Unique Identifier (UUID).
Definition: common/UUID.h:76
Representation of a GattServer attribute.
ble::attribute_handle_t Handle_t
Representation of an attribute handle.
uint16_t * getLengthPtr()
Get a pointer to the current length of the attribute value.
Security_t getWriteSecurityRequirement() const
Return the security level required by write operations.
GattAttribute(const UUID &uuid, uint8_t *valuePtr=nullptr, uint16_t len=0, uint16_t maxLen=0, bool hasVariableLen=true)
Construct an attribute.
static const uint8_t size
Number of bits required to store the value.
bool isWriteAllowed() const
Indicate if a client is allowed to write the attribute.
bool isReadAllowed() const
Indicate if a client is allowed to read the attribute.
bool hasVariableLength() const
Check whether the length of the attribute&#39;s value can change throughout time.
uint16_t getLength() const
Get the current length of the attribute value.
uint16_t attribute_handle_t
Reference to an attribute in a GATT database.
void setWriteSecurityRequirement(Security_t requirement)
Set the security requirements of the write operations.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.