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