1 /** @file
2 * @brief Generic Attribute Profile handling.
3 */
4
5 /*
6 * Copyright (c) 2015-2016 Intel Corporation
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10 #ifndef __BT_GATT_H
11 #define __BT_GATT_H
12
13 /**
14 * @brief Generic Attribute Profile (GATT)
15 * @defgroup bt_gatt Generic Attribute Profile (GATT)
16 * @ingroup bluetooth
17 * @{
18 */
19
20 #include <stddef.h>
21 #include <sys/types.h>
22 #include <misc/util.h>
23 #include <bluetooth/conn.h>
24 #include <bluetooth/uuid.h>
25 #include <bluetooth/att.h>
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /** GATT attribute permission bit field values */
32 enum {
33 /** No operations supported, e.g. for notify-only */
34 BT_GATT_PERM_NONE = 0,
35
36 /** Attribute read permission. */
37 BT_GATT_PERM_READ = BIT(0),
38
39 /** Attribute write permission. */
40 BT_GATT_PERM_WRITE = BIT(1),
41
42 /** @brief Attribute read permission with encryption.
43 *
44 * If set, requires encryption for read access.
45 */
46 BT_GATT_PERM_READ_ENCRYPT = BIT(2),
47
48 /** @brief Attribute write permission with encryption.
49 *
50 * If set, requires encryption for write access.
51 */
52 BT_GATT_PERM_WRITE_ENCRYPT = BIT(3),
53
54 /** @brief Attribute read permission with authentication.
55 *
56 * If set, requires encryption using authenticated link-key for read
57 * access.
58 */
59 BT_GATT_PERM_READ_AUTHEN = BIT(4),
60
61 /** @brief Attribute write permission with authentication.
62 *
63 * If set, requires encryption using authenticated link-key for write
64 * access.
65 */
66 BT_GATT_PERM_WRITE_AUTHEN = BIT(5),
67
68 /** @brief Attribute prepare write permission.
69 *
70 * If set, allows prepare writes with use of BT_GATT_WRITE_FLAG_PREPARE
71 * passed to write callback.
72 */
73 BT_GATT_PERM_PREPARE_WRITE = BIT(6),
74 };
75
76 /** @def BT_GATT_ERR
77 * @brief Construct error return value for attribute read and write callbacks.
78 *
79 * @param _att_err ATT error code
80 *
81 * @return Appropriate error code for the attribute callbacks.
82 */
83 #define BT_GATT_ERR(_att_err) (-(_att_err))
84
85 /** GATT attribute write flags */
86 enum {
87 /** @brief Attribute prepare write flag
88 *
89 * If set, write callback should only check if the device is
90 * authorized but no data shall be written.
91 */
92 BT_GATT_WRITE_FLAG_PREPARE = BIT(0),
93
94 /** @brief Attribute write command flag
95 *
96 * If set, indicates that write operation is a command (Write without
97 * response) which doesn't generate any response.
98 */
99 BT_GATT_WRITE_FLAG_CMD = BIT(1),
100 };
101
102 /** @brief GATT Attribute structure. */
103 struct bt_gatt_attr {
104 /** Attribute UUID */
105 const struct bt_uuid *uuid;
106
107 /** @brief Attribute read callback
108 *
109 * The callback can also be used locally to read the contents of the
110 * attribute in which case no connection will be set.
111 *
112 * @param conn The connection that is requesting to read
113 * @param attr The attribute that's being read
114 * @param buf Buffer to place the read result in
115 * @param len Length of data to read
116 * @param offset Offset to start reading from
117 *
118 * @return Number fo bytes read, or in case of an error
119 * BT_GATT_ERR() with a specific ATT error code.
120 */
121 ssize_t (*read)(struct bt_conn *conn,
122 const struct bt_gatt_attr *attr,
123 void *buf, u16_t len,
124 u16_t offset);
125
126 /** @brief Attribute write callback
127 *
128 * The callback can also be used locally to read the contents of the
129 * attribute in which case no connection will be set.
130 *
131 * @param conn The connection that is requesting to write
132 * @param attr The attribute that's being written
133 * @param buf Buffer with the data to write
134 * @param len Number of bytes in the buffer
135 * @param offset Offset to start writing from
136 * @param flags Flags (BT_GATT_WRITE_*)
137 *
138 * @return Number of bytes written, or in case of an error
139 * BT_GATT_ERR() with a specific ATT error code.
140 */
141 ssize_t (*write)(struct bt_conn *conn,
142 const struct bt_gatt_attr *attr,
143 const void *buf, u16_t len,
144 u16_t offset, u8_t flags);
145
146 /** Attribute user data */
147 void *user_data;
148 /** Attribute handle */
149 u16_t handle;
150 /** Attribute permissions */
151 u8_t perm;
152 };
153
154 /** @brief GATT Service structure */
155 struct bt_gatt_service_static {
156 /** Service Attributes */
157 const struct bt_gatt_attr *attrs;
158 /** Service Attribute count */
159 size_t attr_count;
160 };
161
162 /** @brief GATT Service structure */
163 struct bt_gatt_service {
164 /** Service Attributes */
165 struct bt_gatt_attr *attrs;
166 /** Service Attribute count */
167 size_t attr_count;
168 sys_snode_t node;
169 };
170
171 /** @brief Service Attribute Value. */
172 struct bt_gatt_service_val {
173 /** Service UUID. */
174 const struct bt_uuid *uuid;
175 /** Service end handle. */
176 u16_t end_handle;
177 };
178
179 /** @brief Include Attribute Value. */
180 struct bt_gatt_include {
181 /** Service UUID. */
182 const struct bt_uuid *uuid;
183 /** Service start handle. */
184 u16_t start_handle;
185 /** Service end handle. */
186 u16_t end_handle;
187 };
188
189 /** Characteristic Properties Bit field values */
190
191 /** @def BT_GATT_CHRC_BROADCAST
192 * @brief Characteristic broadcast property.
193 *
194 * If set, permits broadcasts of the Characteristic Value using Server
195 * Characteristic Configuration Descriptor.
196 */
197 #define BT_GATT_CHRC_BROADCAST 0x01
198 /** @def BT_GATT_CHRC_READ
199 * @brief Characteristic read property.
200 *
201 * If set, permits reads of the Characteristic Value.
202 */
203 #define BT_GATT_CHRC_READ 0x02
204 /** @def BT_GATT_CHRC_WRITE_WITHOUT_RESP
205 * @brief Characteristic write without response property.
206 *
207 * If set, permits write of the Characteristic Value without response.
208 */
209 #define BT_GATT_CHRC_WRITE_WITHOUT_RESP 0x04
210 /** @def BT_GATT_CHRC_WRITE
211 * @brief Characteristic write with response property.
212 *
213 * If set, permits write of the Characteristic Value with response.
214 */
215 #define BT_GATT_CHRC_WRITE 0x08
216 /** @def BT_GATT_CHRC_NOTIFY
217 * @brief Characteristic notify property.
218 *
219 * If set, permits notifications of a Characteristic Value without
220 * acknowledgment.
221 */
222 #define BT_GATT_CHRC_NOTIFY 0x10
223 /** @def BT_GATT_CHRC_INDICATE
224 * @brief Characteristic indicate property.
225 *
226 * If set, permits indications of a Characteristic Value with acknowledgment.
227 */
228 #define BT_GATT_CHRC_INDICATE 0x20
229 /** @def BT_GATT_CHRC_AUTH
230 * @brief Characteristic Authenticated Signed Writes property.
231 *
232 * If set, permits signed writes to the Characteristic Value.
233 */
234 #define BT_GATT_CHRC_AUTH 0x40
235 /** @def BT_GATT_CHRC_EXT_PROP
236 * @brief Characteristic Extended Properties property.
237 *
238 * If set, additional characteristic properties are defined in the
239 * Characteristic Extended Properties Descriptor.
240 */
241 #define BT_GATT_CHRC_EXT_PROP 0x80
242
243 /** @brief Characteristic Attribute Value. */
244 struct bt_gatt_chrc {
245 /** Characteristic UUID. */
246 const struct bt_uuid *uuid;
247 /** Characteristic Value handle. */
248 u16_t value_handle;
249 /** Characteristic properties. */
250 u8_t properties;
251 };
252
253 /** Characteristic Extended Properties Bit field values */
254 #define BT_GATT_CEP_RELIABLE_WRITE 0x0001
255 #define BT_GATT_CEP_WRITABLE_AUX 0x0002
256
257 /** @brief Characteristic Extended Properties Attribute Value. */
258 struct bt_gatt_cep {
259 /** Characteristic Extended properties */
260 u16_t properties;
261 };
262
263 /** Client Characteristic Configuration Values */
264
265 /** @def BT_GATT_CCC_NOTIFY
266 * @brief Client Characteristic Configuration Notification.
267 *
268 * If set, changes to Characteristic Value shall be notified.
269 */
270 #define BT_GATT_CCC_NOTIFY 0x0001
271 /** @def BT_GATT_CCC_INDICATE
272 * @brief Client Characteristic Configuration Indication.
273 *
274 * If set, changes to Characteristic Value shall be indicated.
275 */
276 #define BT_GATT_CCC_INDICATE 0x0002
277
278 /** Client Characteristic Configuration Attribute Value */
279 struct bt_gatt_ccc {
280 /** Client Characteristic Configuration flags */
281 u16_t flags;
282 };
283
284 /** @brief GATT Characteristic Presentation Format Attribute Value. */
285 struct bt_gatt_cpf {
286 /** Format of the value of the characteristic */
287 u8_t format;
288 /** Exponent field to determine how the value of this characteristic is
289 * further formatted
290 */
291 s8_t exponent;
292 /** Unit of the characteristic */
293 u16_t unit;
294 /** Name space of the description */
295 u8_t name_space;
296 /** Description of the characteristic as defined in a higher layer profile */
297 u16_t description;
298 } __packed;
299
300 /**
301 * @defgroup bt_gatt_server GATT Server APIs
302 * @ingroup bt_gatt
303 * @{
304 */
305
306 /** @brief Register GATT service.
307 *
308 * Register GATT service. Applications can make use of
309 * macros such as BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC,
310 * BT_GATT_DESCRIPTOR, etc.
311 *
312 * When using :option:`CONFIG_BT_GATT_CACHING` and :option:`CONFIG_BT_SETTINGS`
313 * then all services that should be included in the GATT Database Hash
314 * calculation should be added before calling @ref settings_load.
315 * All services registered after settings_load will trigger a new database hash
316 * calculation and a new hash stored.
317 *
318 * @param svc Service containing the available attributes
319 *
320 * @return 0 in case of success or negative value in case of error.
321 */
322 int bt_gatt_service_register(struct bt_gatt_service *svc);
323
324 /** @brief Unregister GATT service.
325 * *
326 * @param svc Service to be unregistered.
327 *
328 * @return 0 in case of success or negative value in case of error.
329 */
330 int bt_gatt_service_unregister(struct bt_gatt_service *svc);
331
332 enum {
333 BT_GATT_ITER_STOP = 0,
334 BT_GATT_ITER_CONTINUE,
335 };
336
337 /** @typedef bt_gatt_attr_func_t
338 * @brief Attribute iterator callback.
339 *
340 * @param attr Attribute found.
341 * @param user_data Data given.
342 *
343 * @return BT_GATT_ITER_CONTINUE if should continue to the next attribute.
344 * @return BT_GATT_ITER_STOP to stop.
345 */
346 typedef u8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr,
347 void *user_data);
348
349 /** @brief Attribute iterator by type.
350 *
351 * Iterate attributes in the given range matching given UUID and/or data.
352 *
353 * @param start_handle Start handle.
354 * @param end_handle End handle.
355 * @param uuid UUID to match, passing NULL skips UUID matching.
356 * @param attr_data Attribute data to match, passing NULL skips data matching.
357 * @param num_matches Number matches, passing 0 makes it unlimited.
358 * @param func Callback function.
359 * @param user_data Data to pass to the callback.
360 */
361 void bt_gatt_foreach_attr_type(u16_t start_handle, u16_t end_handle,
362 const struct bt_uuid *uuid,
363 const void *attr_data, uint16_t num_matches,
364 bt_gatt_attr_func_t func,
365 void *user_data);
366
367 /** @brief Attribute iterator.
368 *
369 * Iterate attributes in the given range.
370 *
371 * @param start_handle Start handle.
372 * @param end_handle End handle.
373 * @param func Callback function.
374 * @param user_data Data to pass to the callback.
375 */
bt_gatt_foreach_attr(u16_t start_handle,u16_t end_handle,bt_gatt_attr_func_t func,void * user_data)376 static inline void bt_gatt_foreach_attr(u16_t start_handle, u16_t end_handle,
377 bt_gatt_attr_func_t func,
378 void *user_data)
379 {
380 bt_gatt_foreach_attr_type(start_handle, end_handle, NULL, NULL, 0, func,
381 user_data);
382 }
383
384 /** @brief Iterate to the next attribute
385 *
386 * Iterate to the next attribute following a given attribute.
387 *
388 * @param attr Current Attribute.
389 *
390 * @return The next attribute or NULL if it cannot be found.
391 */
392 struct bt_gatt_attr *bt_gatt_attr_next(const struct bt_gatt_attr *attr);
393
394 /** @brief Get the handle of the characteristic value descriptor.
395 *
396 * @param attr A Characteristic Attribute
397 *
398 * @return the handle of the corresponding Characteristic Value. The value will
399 * be zero (the invalid handle) if @p attr was not a characteristic
400 * attribute.
401 */
402 uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr);
403
404 /** @brief Generic Read Attribute value helper.
405 *
406 * Read attribute value from local database storing the result into buffer.
407 *
408 * @param conn Connection object.
409 * @param attr Attribute to read.
410 * @param buf Buffer to store the value.
411 * @param buf_len Buffer length.
412 * @param offset Start offset.
413 * @param value Attribute value.
414 * @param value_len Length of the attribute value.
415 *
416 * @return number of bytes read in case of success or negative values in
417 * case of error.
418 */
419 ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr,
420 void *buf, u16_t buf_len, u16_t offset,
421 const void *value, u16_t value_len);
422
423 /** @brief Read Service Attribute helper.
424 *
425 * Read service attribute value from local database storing the result into
426 * buffer after encoding it.
427 * @note Only use this with attributes which user_data is a bt_uuid.
428 *
429 * @param conn Connection object.
430 * @param attr Attribute to read.
431 * @param buf Buffer to store the value read.
432 * @param len Buffer length.
433 * @param offset Start offset.
434 *
435 * @return number of bytes read in case of success or negative values in
436 * case of error.
437 */
438 ssize_t bt_gatt_attr_read_service(struct bt_conn *conn,
439 const struct bt_gatt_attr *attr,
440 void *buf, u16_t len, u16_t offset);
441
442 /** @def BT_GATT_SERVICE_DEFINE
443 * @brief Statically define and register a service.
444 *
445 * Helper macro to statically define and register a service.
446 *
447 * @param _name Service name.
448 */
449 #define BT_GATT_SERVICE_DEFINE(_name, ...) \
450 struct bt_gatt_attr attr_##_name[] = { __VA_ARGS__ }; \
451 const Z_STRUCT_SECTION_ITERABLE(bt_gatt_service_static, _name) =\
452 BT_GATT_SERVICE(attr_##_name)
453
454 /** @def BT_GATT_SERVICE
455 * @brief Service Structure Declaration Macro.
456 *
457 * Helper macro to declare a service structure.
458 *
459 * @param _attrs Service attributes.
460 */
461 #define BT_GATT_SERVICE(_attrs) \
462 { \
463 .attrs = _attrs, \
464 .attr_count = ARRAY_SIZE(_attrs), \
465 }
466
467 /** @def BT_GATT_PRIMARY_SERVICE
468 * @brief Primary Service Declaration Macro.
469 *
470 * Helper macro to declare a primary service attribute.
471 *
472 * @param _service Service attribute value.
473 */
474 #define BT_GATT_PRIMARY_SERVICE(_service) \
475 BT_GATT_ATTRIBUTE(BT_UUID_GATT_PRIMARY, BT_GATT_PERM_READ, \
476 bt_gatt_attr_read_service, NULL, _service)
477
478 /** @def BT_GATT_SECONDARY_SERVICE
479 * @brief Secondary Service Declaration Macro.
480 *
481 * Helper macro to declare a secondary service attribute.
482 *
483 * @param _service Service attribute value.
484 */
485 #define BT_GATT_SECONDARY_SERVICE(_service) \
486 BT_GATT_ATTRIBUTE(BT_UUID_GATT_SECONDARY, BT_GATT_PERM_READ, \
487 bt_gatt_attr_read_service, NULL, _service)
488
489 /** @brief Read Include Attribute helper.
490 *
491 * Read include service attribute value from local database storing the result
492 * into buffer after encoding it.
493 * @note Only use this with attributes which user_data is a bt_gatt_include.
494 *
495 * @param conn Connection object.
496 * @param attr Attribute to read.
497 * @param buf Buffer to store the value read.
498 * @param len Buffer length.
499 * @param offset Start offset.
500 *
501 * @return number of bytes read in case of success or negative values in
502 * case of error.
503 */
504 ssize_t bt_gatt_attr_read_included(struct bt_conn *conn,
505 const struct bt_gatt_attr *attr,
506 void *buf, u16_t len, u16_t offset);
507
508 /** @def BT_GATT_INCLUDE_SERVICE
509 * @brief Include Service Declaration Macro.
510 *
511 * Helper macro to declare database internal include service attribute.
512 *
513 * @param _service_incl the first service attribute of service to include
514 */
515 #define BT_GATT_INCLUDE_SERVICE(_service_incl) \
516 BT_GATT_ATTRIBUTE(BT_UUID_GATT_INCLUDE, BT_GATT_PERM_READ, \
517 bt_gatt_attr_read_included, NULL, _service_incl)
518
519 /** @brief Read Characteristic Attribute helper.
520 *
521 * Read characteristic attribute value from local database storing the result
522 * into buffer after encoding it.
523 * @note Only use this with attributes which user_data is a bt_gatt_chrc.
524 *
525 * @param conn Connection object.
526 * @param attr Attribute to read.
527 * @param buf Buffer to store the value read.
528 * @param len Buffer length.
529 * @param offset Start offset.
530 *
531 * @return number of bytes read in case of success or negative values in
532 * case of error.
533 */
534 ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn,
535 const struct bt_gatt_attr *attr, void *buf,
536 u16_t len, u16_t offset);
537
538 /** @def BT_GATT_CHARACTERISTIC
539 * @brief Characteristic and Value Declaration Macro.
540 *
541 * Helper macro to declare a characteristic attribute along with its
542 * attribute value.
543 *
544 * @param _uuid Characteristic attribute uuid.
545 * @param _props Characteristic attribute properties.
546 * @param _perm Characteristic Attribute access permissions.
547 * @param _read Characteristic Attribute read callback.
548 * @param _write Characteristic Attribute write callback.
549 * @param _value Characteristic Attribute value.
550 */
551 #define BT_GATT_CHARACTERISTIC(_uuid, _props, _perm, _read, _write, _value) \
552 BT_GATT_ATTRIBUTE(BT_UUID_GATT_CHRC, BT_GATT_PERM_READ, \
553 bt_gatt_attr_read_chrc, NULL, \
554 ((struct bt_gatt_chrc[]) { { .uuid = _uuid, \
555 .value_handle = 0U, \
556 .properties = _props, \
557 } })), \
558 BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _value)
559
560 #if IS_ENABLED(CONFIG_BT_SETTINGS_CCC_LAZY_LOADING)
561 #define BT_GATT_CCC_MAX (CONFIG_BT_MAX_CONN)
562 #else
563 #define BT_GATT_CCC_MAX (CONFIG_BT_MAX_PAIRED + CONFIG_BT_MAX_CONN)
564 #endif
565
566 /** @brief GATT CCC configuration entry.
567 *
568 * @param id Local identity, BT_ID_DEFAULT in most cases.
569 * @param peer Remote peer address
570 * @param value Configuration value.
571 * @param data Configuration pointer data.
572 */
573 struct bt_gatt_ccc_cfg {
574 u8_t id;
575 bt_addr_le_t peer;
576 u16_t value;
577 };
578
579 /** Internal representation of CCC value */
580 struct _bt_gatt_ccc {
581 /** Configuration for each connection */
582 struct bt_gatt_ccc_cfg cfg[BT_GATT_CCC_MAX];
583
584 /** Highest value of all connected peer's subscriptions */
585 u16_t value;
586
587 /** @brief CCC attribute changed callback
588 *
589 * @param attr The attribute that's changed value
590 * @param value New value
591 */
592 void (*cfg_changed)(const struct bt_gatt_attr *attr, u16_t value);
593
594 /** @brief CCC attribute write validation callback
595 *
596 * @param conn The connection that is requesting to write
597 * @param attr The attribute that's being written
598 * @param value CCC value to write
599 *
600 * @return Number of bytes to write, or in case of an error
601 * BT_GATT_ERR() with a specific error code.
602 */
603 ssize_t (*cfg_write)(struct bt_conn *conn,
604 const struct bt_gatt_attr *attr, u16_t value);
605
606 /** @brief CCC attribute match handler
607 *
608 * Indicate if it is OK to send a notification or indication
609 * to the subscriber.
610 *
611 * @param conn The connection that is being checked
612 * @param attr The attribute that's being checked
613 *
614 * @return true if application has approved notification/indication,
615 * false if application does not approve.
616 */
617 bool (*cfg_match)(struct bt_conn *conn,
618 const struct bt_gatt_attr *attr);
619 };
620
621 /** @brief Read Client Characteristic Configuration Attribute helper.
622 *
623 * Read CCC attribute value from local database storing the result into buffer
624 * after encoding it.
625 *
626 * @note Only use this with attributes which user_data is a _bt_gatt_ccc.
627 *
628 * @param conn Connection object.
629 * @param attr Attribute to read.
630 * @param buf Buffer to store the value read.
631 * @param len Buffer length.
632 * @param offset Start offset.
633 *
634 * @return number of bytes read in case of success or negative values in
635 * case of error.
636 */
637 ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
638 const struct bt_gatt_attr *attr, void *buf,
639 u16_t len, u16_t offset);
640
641 /** @brief Write Client Characteristic Configuration Attribute helper.
642 *
643 * Write value in the buffer into CCC attribute.
644 *
645 * @note Only use this with attributes which user_data is a _bt_gatt_ccc.
646 *
647 * @param conn Connection object.
648 * @param attr Attribute to read.
649 * @param buf Buffer to store the value read.
650 * @param len Buffer length.
651 * @param offset Start offset.
652 * @param flags Write flags.
653 *
654 * @return number of bytes written in case of success or negative values in
655 * case of error.
656 */
657 ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
658 const struct bt_gatt_attr *attr, const void *buf,
659 u16_t len, u16_t offset, u8_t flags);
660
661
662 /** @def BT_GATT_CCC_INITIALIZER
663 * @brief Initialize Client Characteristic Configuration Declaration Macro.
664 *
665 * Helper macro to initialize a Managed CCC attribute value.
666 *
667 * @param _changed Configuration changed callback.
668 * @param _write Configuration write callback.
669 * @param _match Configuration match callback.
670 */
671 #define BT_GATT_CCC_INITIALIZER(_changed, _write, _match) \
672 { \
673 .cfg = {{0}}, \
674 .cfg_changed = _changed, \
675 .cfg_write = _write, \
676 .cfg_match = _match, \
677 }
678
679 /** @def BT_GATT_CCC_MANAGED
680 * @brief Managed Client Characteristic Configuration Declaration Macro.
681 *
682 * Helper macro to declare a Managed CCC attribute.
683 *
684 * @param _ccc CCC attribute user data, shall point to a _bt_gatt_ccc.
685 * @param _perm CCC access permissions.
686 */
687 #define BT_GATT_CCC_MANAGED(_ccc, _perm) \
688 BT_GATT_ATTRIBUTE(BT_UUID_GATT_CCC, _perm, \
689 bt_gatt_attr_read_ccc, bt_gatt_attr_write_ccc, \
690 _ccc)
691
692 /** @def BT_GATT_CCC
693 * @brief Client Characteristic Configuration Declaration Macro.
694 *
695 * Helper macro to declare a CCC attribute.
696 *
697 * @param _changed Configuration changed callback.
698 * @param _perm CCC access permissions.
699 */
700 #define BT_GATT_CCC(_changed, _perm) \
701 BT_GATT_CCC_MANAGED(((struct _bt_gatt_ccc[]) \
702 {BT_GATT_CCC_INITIALIZER(_changed, NULL, NULL)}), _perm)
703
704 /** @brief Read Characteristic Extended Properties Attribute helper
705 *
706 * Read CEP attribute value from local database storing the result into buffer
707 * after encoding it.
708 *
709 * @note Only use this with attributes which user_data is a bt_gatt_cep.
710 *
711 * @param conn Connection object
712 * @param attr Attribute to read
713 * @param buf Buffer to store the value read
714 * @param len Buffer length
715 * @param offset Start offset
716 *
717 * @return number of bytes read in case of success or negative values in
718 * case of error.
719 */
720 ssize_t bt_gatt_attr_read_cep(struct bt_conn *conn,
721 const struct bt_gatt_attr *attr, void *buf,
722 u16_t len, u16_t offset);
723
724 /** @def BT_GATT_CEP
725 * @brief Characteristic Extended Properties Declaration Macro.
726 *
727 * Helper macro to declare a CEP attribute.
728 *
729 * @param _value Descriptor attribute value.
730 */
731 #define BT_GATT_CEP(_value) \
732 BT_GATT_DESCRIPTOR(BT_UUID_GATT_CEP, BT_GATT_PERM_READ, \
733 bt_gatt_attr_read_cep, NULL, (void *)_value)
734
735 /** @brief Read Characteristic User Description Descriptor Attribute helper
736 *
737 * Read CUD attribute value from local database storing the result into buffer
738 * after encoding it.
739 *
740 * @note Only use this with attributes which user_data is a NULL-terminated C
741 * string.
742 *
743 * @param conn Connection object
744 * @param attr Attribute to read
745 * @param buf Buffer to store the value read
746 * @param len Buffer length
747 * @param offset Start offset
748 *
749 * @return number of bytes read in case of success or negative values in
750 * case of error.
751 */
752 ssize_t bt_gatt_attr_read_cud(struct bt_conn *conn,
753 const struct bt_gatt_attr *attr, void *buf,
754 u16_t len, u16_t offset);
755
756 /** @def BT_GATT_CUD
757 * @brief Characteristic User Format Descriptor Declaration Macro.
758 *
759 * Helper macro to declare a CUD attribute.
760 *
761 * @param _value User description NULL-terminated C string.
762 * @param _perm Descriptor attribute access permissions.
763 */
764 #define BT_GATT_CUD(_value, _perm) \
765 BT_GATT_DESCRIPTOR(BT_UUID_GATT_CUD, _perm, bt_gatt_attr_read_cud, \
766 NULL, (void *)_value)
767
768 /** @brief Read Characteristic Presentation format Descriptor Attribute helper
769 *
770 * Read CPF attribute value from local database storing the result into buffer
771 * after encoding it.
772 *
773 * @note Only use this with attributes which user_data is a bt_gatt_pf.
774 *
775 * @param conn Connection object
776 * @param attr Attribute to read
777 * @param buf Buffer to store the value read
778 * @param len Buffer length
779 * @param offset Start offset
780 *
781 * @return number of bytes read in case of success or negative values in
782 * case of error.
783 */
784 ssize_t bt_gatt_attr_read_cpf(struct bt_conn *conn,
785 const struct bt_gatt_attr *attr, void *buf,
786 u16_t len, u16_t offset);
787
788 /** @def BT_GATT_CPF
789 * @brief Characteristic Presentation Format Descriptor Declaration Macro.
790 *
791 * Helper macro to declare a CPF attribute.
792 *
793 * @param _value Descriptor attribute value.
794 */
795 #define BT_GATT_CPF(_value) \
796 BT_GATT_DESCRIPTOR(BT_UUID_GATT_CPF, BT_GATT_PERM_READ, \
797 bt_gatt_attr_read_cpf, NULL, (void *)_value)
798
799 /** @def BT_GATT_DESCRIPTOR
800 * @brief Descriptor Declaration Macro.
801 *
802 * Helper macro to declare a descriptor attribute.
803 *
804 * @param _uuid Descriptor attribute uuid.
805 * @param _perm Descriptor attribute access permissions.
806 * @param _read Descriptor attribute read callback.
807 * @param _write Descriptor attribute write callback.
808 * @param _value Descriptor attribute value.
809 */
810 #define BT_GATT_DESCRIPTOR(_uuid, _perm, _read, _write, _value) \
811 BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _value)
812
813 /** @def BT_GATT_ATTRIBUTE
814 * @brief Attribute Declaration Macro.
815 *
816 * Helper macro to declare an attribute.
817 *
818 * @param _uuid Attribute uuid.
819 * @param _perm Attribute access permissions.
820 * @param _read Attribute read callback.
821 * @param _write Attribute write callback.
822 * @param _value Attribute value.
823 */
824 #define BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _value) \
825 { \
826 .uuid = _uuid, \
827 .read = _read, \
828 .write = _write, \
829 .user_data = _value, \
830 .handle = 0, \
831 .perm = _perm, \
832 }
833
834 /** @brief Notification complete result callback.
835 *
836 * @param conn Connection object.
837 */
838 typedef void (*bt_gatt_complete_func_t) (struct bt_conn *conn, void *user_data);
839
840 struct bt_gatt_notify_params {
841 /** Notification Attribute UUID type */
842 const struct bt_uuid *uuid;
843 /** Notification Attribute object*/
844 const struct bt_gatt_attr *attr;
845 /** Notification Value data */
846 const void *data;
847 /** Notification Value length */
848 u16_t len;
849 /** Notification Value callback */
850 bt_gatt_complete_func_t func;
851 /** Notification Value callback user data */
852 void *user_data;
853 };
854
855 /** @brief Notify attribute value change.
856 *
857 * This function works in the same way as @ref bt_gatt_notify.
858 * With the addition that after sending the notification the
859 * callback function will be called.
860 *
861 * The callback is run from System Workqueue context.
862 *
863 * Alternatively it is possible to notify by UUID by setting it on the
864 * parameters, when using this method the attribute given is used as the
865 * start range when looking up for possible matches.
866 *
867 * @param conn Connection object.
868 * @param params Notification parameters.
869 *
870 * @return 0 in case of success or negative value in case of error.
871 */
872 int bt_gatt_notify_cb(struct bt_conn *conn,
873 struct bt_gatt_notify_params *params);
874
875 /** @brief Notify multiple attribute value change.
876 *
877 * @param conn Connection object.
878 * @param num_params Number of notification parameters.
879 * @param params Array of notification parameters.
880 *
881 * @return 0 in case of success or negative value in case of error.
882 */
883 int bt_gatt_notify_multiple(struct bt_conn *conn, u16_t num_params,
884 struct bt_gatt_notify_params *params);
885
886 /** @brief Notify attribute value change.
887 *
888 * Send notification of attribute value change, if connection is NULL notify
889 * all peer that have notification enabled via CCC otherwise do a direct
890 * notification only the given connection.
891 *
892 * The attribute object on the parameters can be the so called Characteristic
893 * Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed
894 * by BT_GATT_CCC, or the Characteristic Value Declaration which is
895 * automatically created after the Characteristic Declaration when using
896 * BT_GATT_CHARACTERISTIC.
897 *
898 * @param conn Connection object.
899 * @param attr Characteristic or Characteristic Value attribute.
900 * @param data Pointer to Attribute data.
901 * @param len Attribute value length.
902 *
903 * @return 0 in case of success or negative value in case of error.
904 */
bt_gatt_notify(struct bt_conn * conn,const struct bt_gatt_attr * attr,const void * data,u16_t len)905 static inline int bt_gatt_notify(struct bt_conn *conn,
906 const struct bt_gatt_attr *attr,
907 const void *data, u16_t len)
908 {
909 struct bt_gatt_notify_params params;
910
911 memset(¶ms, 0, sizeof(params));
912
913 params.attr = attr;
914 params.data = data;
915 params.len = len;
916
917 return bt_gatt_notify_cb(conn, ¶ms);
918 }
919
920 /** @typedef bt_gatt_indicate_func_t
921 * @brief Indication complete result callback.
922 *
923 * @param conn Connection object.
924 * @param attr Attribute object.
925 * @param err ATT error code
926 */
927 typedef void (*bt_gatt_indicate_func_t)(struct bt_conn *conn,
928 const struct bt_gatt_attr *attr,
929 u8_t err);
930
931 /** @brief GATT Indicate Value parameters */
932 struct bt_gatt_indicate_params {
933 /** Notification Attribute UUID type */
934 const struct bt_uuid *uuid;
935 /** Indicate Attribute object*/
936 const struct bt_gatt_attr *attr;
937 /** Indicate Value callback */
938 bt_gatt_indicate_func_t func;
939 /** Indicate Value data*/
940 const void *data;
941 /** Indicate Value length*/
942 u16_t len;
943 };
944
945 /** @brief Indicate attribute value change.
946 *
947 * Send an indication of attribute value change. if connection is NULL
948 * indicate all peer that have notification enabled via CCC otherwise do a
949 * direct indication only the given connection.
950 *
951 * The attribute object on the parameters can be the so called Characteristic
952 * Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed
953 * by BT_GATT_CCC, or the Characteristic Value Declaration which is
954 * automatically created after the Characteristic Declaration when using
955 * BT_GATT_CHARACTERISTIC.
956 *
957 * The callback is run from System Workqueue context.
958 *
959 * Alternatively it is possible to indicate by UUID by setting it on the
960 * parameters, when using this method the attribute given is used as the
961 * start range when looking up for possible matches.
962 *
963 * @note This procedure is asynchronous therefore the parameters need to
964 * remains valid while it is active.
965 *
966 * @param conn Connection object.
967 * @param params Indicate parameters.
968 *
969 * @return 0 in case of success or negative value in case of error.
970 */
971 int bt_gatt_indicate(struct bt_conn *conn,
972 struct bt_gatt_indicate_params *params);
973
974
975 /** @brief Check if connection have subscribed to attribute
976 *
977 * Check if connection has subscribed to attribute value change.
978 *
979 * The attribute object can be the so called Characteristic Declaration,
980 * which is usually declared with BT_GATT_CHARACTERISTIC followed
981 * by BT_GATT_CCC, or the Characteristic Value Declaration which is
982 * automatically created after the Characteristic Declaration when using
983 * BT_GATT_CHARACTERISTIC, or the Client Characteristic Configuration
984 * Descriptor (CCCD) which is created by BT_GATT_CCC.
985 *
986 * @param conn Connection object.
987 * @param attr Attribute object.
988 * @param ccc_value The subscription type, either notifications or indications.
989 *
990 * @return true if the attribute object has been subscribed.
991 */
992 bool bt_gatt_is_subscribed(struct bt_conn *conn,
993 const struct bt_gatt_attr *attr, u16_t ccc_value);
994
995 /** @brief Get ATT MTU for a connection
996 *
997 * Get negotiated ATT connection MTU, note that this does not equal the largest
998 * amount of attribute data that can be transferred within a single packet.
999 *
1000 * @param conn Connection object.
1001 *
1002 * @return MTU in bytes
1003 */
1004 u16_t bt_gatt_get_mtu(struct bt_conn *conn);
1005
1006 /** @} */
1007
1008 /**
1009 * @defgroup bt_gatt_client GATT Client APIs
1010 * @ingroup bt_gatt
1011 * @{
1012 */
1013
1014 /** @brief GATT Exchange MTU parameters */
1015 struct bt_gatt_exchange_params {
1016 /** Response callback */
1017 void (*func)(struct bt_conn *conn, u8_t err,
1018 struct bt_gatt_exchange_params *params);
1019 };
1020
1021 /** @brief Exchange MTU
1022 *
1023 * This client procedure can be used to set the MTU to the maximum possible
1024 * size the buffers can hold.
1025 *
1026 * @note Shall only be used once per connection.
1027 *
1028 * @param conn Connection object.
1029 * @param params Exchange MTU parameters.
1030 *
1031 * @return 0 in case of success or negative value in case of error.
1032 */
1033 int bt_gatt_exchange_mtu(struct bt_conn *conn,
1034 struct bt_gatt_exchange_params *params);
1035
1036 struct bt_gatt_discover_params;
1037
1038 /** @typedef bt_gatt_discover_func_t
1039 * @brief Discover attribute callback function.
1040 *
1041 * @param conn Connection object.
1042 * @param attr Attribute found.
1043 * @param params Discovery parameters given.
1044 *
1045 * If discovery procedure has completed this callback will be called with
1046 * attr set to NULL. This will not happen if procedure was stopped by returning
1047 * BT_GATT_ITER_STOP. The attribute is read-only and cannot be cached without
1048 * copying its contents.
1049 *
1050 * @return BT_GATT_ITER_CONTINUE if should continue attribute discovery.
1051 * @return BT_GATT_ITER_STOP to stop discovery procedure.
1052 */
1053 typedef u8_t (*bt_gatt_discover_func_t)(struct bt_conn *conn,
1054 const struct bt_gatt_attr *attr,
1055 struct bt_gatt_discover_params *params);
1056
1057 /** GATT Discover types */
1058 enum {
1059 /** Discover Primary Services. */
1060 BT_GATT_DISCOVER_PRIMARY,
1061 /** Discover Secondary Services. */
1062 BT_GATT_DISCOVER_SECONDARY,
1063 /** Discover Included Services. */
1064 BT_GATT_DISCOVER_INCLUDE,
1065 /** @brief Discover Characteristic Values.
1066 *
1067 * Discover Characteristic Value and its properties.
1068 */
1069 BT_GATT_DISCOVER_CHARACTERISTIC,
1070 /** @brief Discover Descriptors.
1071 *
1072 * Discover Attributes which are not services or characteristics.
1073 *
1074 * @note The use of this type of discover is not recommended for
1075 * discovering in ranges across multiple services/characteristics
1076 * as it may incur in extra round trips.
1077 */
1078 BT_GATT_DISCOVER_DESCRIPTOR,
1079 /** @brief Discover Attributes.
1080 *
1081 * Discover Attributes of any type.
1082 *
1083 * @note The use of this type of discover is not recommended for
1084 * discovering in ranges across multiple services/characteristics
1085 * as it may incur in more round trips.
1086 */
1087 BT_GATT_DISCOVER_ATTRIBUTE,
1088 };
1089
1090 /** @brief GATT Discover Attributes parameters */
1091 struct bt_gatt_discover_params {
1092 /** Discover UUID type */
1093 struct bt_uuid *uuid;
1094 /** Discover attribute callback */
1095 bt_gatt_discover_func_t func;
1096 union {
1097 struct {
1098 /** Include service attribute declaration handle */
1099 u16_t attr_handle;
1100 /** Included service start handle */
1101 u16_t start_handle;
1102 /** Included service end handle */
1103 u16_t end_handle;
1104 } _included;
1105 /** Discover start handle */
1106 u16_t start_handle;
1107 };
1108 /** Discover end handle */
1109 u16_t end_handle;
1110 /** Discover type */
1111 u8_t type;
1112 };
1113
1114 /** @brief GATT Discover function
1115 *
1116 * This procedure is used by a client to discover attributes on a server.
1117 *
1118 * Primary Service Discovery: Procedure allows to discover specific Primary
1119 * Service based on UUID.
1120 * Include Service Discovery: Procedure allows to discover all Include Services
1121 * within specified range.
1122 * Characteristic Discovery: Procedure allows to discover all characteristics
1123 * within specified handle range as well as
1124 * discover characteristics with specified UUID.
1125 * Descriptors Discovery: Procedure allows to discover all characteristic
1126 * descriptors within specified range.
1127 *
1128 * For each attribute found the callback is called which can then decide
1129 * whether to continue discovering or stop.
1130 *
1131 * @note This procedure is asynchronous therefore the parameters need to
1132 * remains valid while it is active.
1133 *
1134 * @param conn Connection object.
1135 * @param params Discover parameters.
1136 *
1137 * @return 0 in case of success or negative value in case of error.
1138 */
1139 int bt_gatt_discover(struct bt_conn *conn,
1140 struct bt_gatt_discover_params *params);
1141
1142 struct bt_gatt_read_params;
1143
1144 /** @typedef bt_gatt_read_func_t
1145 * @brief Read callback function
1146 *
1147 * @param conn Connection object.
1148 * @param err ATT error code.
1149 * @param params Read parameters used.
1150 * @param data Attribute value data. NULL means read has completed.
1151 * @param length Attribute value length.
1152 *
1153 * @return BT_GATT_ITER_CONTINUE if should continue to the next attribute.
1154 * @return BT_GATT_ITER_STOP to stop.
1155 */
1156 typedef u8_t (*bt_gatt_read_func_t)(struct bt_conn *conn, u8_t err,
1157 struct bt_gatt_read_params *params,
1158 const void *data, u16_t length);
1159
1160 /** @brief GATT Read parameters
1161 *
1162 * @param func Read attribute callback
1163 * @param handle_count If equals to 1 single.handle and single.offset
1164 * are used. If >1 Read Multiple Characteristic
1165 * Values is performed and handles are used.
1166 * If equals to 0 by_uuid is used for Read Using
1167 * Characteristic UUID.
1168 * @param handle Attribute handle
1169 * @param offset Attribute data offset
1170 * @param handles Handles to read in Read Multiple Characteristic Values
1171 * @param start_handle First requested handle number
1172 * @param end_handle Last requested handle number
1173 * @param uuid 2 or 16 octet UUID
1174 */
1175 struct bt_gatt_read_params {
1176 bt_gatt_read_func_t func;
1177 size_t handle_count;
1178 union {
1179 struct {
1180 u16_t handle;
1181 u16_t offset;
1182 } single;
1183 u16_t *handles;
1184 struct {
1185 u16_t start_handle;
1186 u16_t end_handle;
1187 struct bt_uuid *uuid;
1188 } by_uuid;
1189 };
1190 };
1191
1192 /** @brief Read Attribute Value by handle
1193 *
1194 * This procedure read the attribute value and return it to the callback.
1195 *
1196 * When reading attributes by UUID the callback can be called multiple times
1197 * depending on how many instances of given the UUID exists with the
1198 * start_handle being updated for each instance.
1199 *
1200 * If an instance does contain a long value which cannot be read entirely the
1201 * caller will need to read the remaining data separately using the handle and
1202 * offset.
1203 *
1204 * @note This procedure is asynchronous therefore the parameters need to
1205 * remains valid while it is active.
1206 *
1207 * @param conn Connection object.
1208 * @param params Read parameters.
1209 *
1210 * @return 0 in case of success or negative value in case of error.
1211 */
1212 int bt_gatt_read(struct bt_conn *conn, struct bt_gatt_read_params *params);
1213
1214 struct bt_gatt_write_params;
1215
1216 /** @typedef bt_gatt_write_func_t
1217 * @brief Write callback function
1218 *
1219 * @param conn Connection object.
1220 * @param err ATT error code.
1221 * @param params Write parameters used.
1222 */
1223 typedef void (*bt_gatt_write_func_t)(struct bt_conn *conn, u8_t err,
1224 struct bt_gatt_write_params *params);
1225
1226 /** @brief GATT Write parameters */
1227 struct bt_gatt_write_params {
1228 /** Response callback */
1229 bt_gatt_write_func_t func;
1230 /** Attribute handle */
1231 u16_t handle;
1232 /** Attribute data offset */
1233 u16_t offset;
1234 /** Data to be written */
1235 const void *data;
1236 /** Length of the data */
1237 u16_t length;
1238 };
1239
1240 /** @brief Write Attribute Value by handle
1241 *
1242 * This procedure write the attribute value and return the result in the
1243 * callback.
1244 *
1245 * @note This procedure is asynchronous therefore the parameters need to
1246 * remains valid while it is active.
1247 *
1248 * @param conn Connection object.
1249 * @param params Write parameters.
1250 *
1251 * @return 0 in case of success or negative value in case of error.
1252 */
1253 int bt_gatt_write(struct bt_conn *conn, struct bt_gatt_write_params *params);
1254
1255 /** @brief Write Attribute Value by handle without response with callback.
1256 *
1257 * This function works in the same way as @ref bt_gatt_write_without_response.
1258 * With the addition that after sending the write the callback function will be
1259 * called.
1260 *
1261 * The callback is run from System Workqueue context.
1262 *
1263 * @note By using a callback it also disable the internal flow control
1264 * which would prevent sending multiple commands without waiting for
1265 * their transmissions to complete, so if that is required the caller
1266 * shall not submit more data until the callback is called.
1267 *
1268 * @param conn Connection object.
1269 * @param handle Attribute handle.
1270 * @param data Data to be written.
1271 * @param length Data length.
1272 * @param sign Whether to sign data
1273 * @param func Transmission complete callback.
1274 * @param user_data User data to be passed back to callback.
1275 *
1276 * @return 0 in case of success or negative value in case of error.
1277 */
1278 int bt_gatt_write_without_response_cb(struct bt_conn *conn, u16_t handle,
1279 const void *data, u16_t length,
1280 bool sign, bt_gatt_complete_func_t func,
1281 void *user_data);
1282
1283 /** @brief Write Attribute Value by handle without response
1284 *
1285 * This procedure write the attribute value without requiring an
1286 * acknowledgment that the write was successfully performed
1287 *
1288 * @param conn Connection object.
1289 * @param handle Attribute handle.
1290 * @param data Data to be written.
1291 * @param length Data length.
1292 * @param sign Whether to sign data
1293 *
1294 * @return 0 in case of success or negative value in case of error.
1295 */
bt_gatt_write_without_response(struct bt_conn * conn,u16_t handle,const void * data,u16_t length,bool sign)1296 static inline int bt_gatt_write_without_response(struct bt_conn *conn,
1297 u16_t handle, const void *data,
1298 u16_t length, bool sign)
1299 {
1300 return bt_gatt_write_without_response_cb(conn, handle, data, length,
1301 sign, NULL, NULL);
1302 }
1303
1304 struct bt_gatt_subscribe_params;
1305
1306 /** @typedef bt_gatt_notify_func_t
1307 * @brief Notification callback function
1308 *
1309 * @param conn Connection object. May be NULL, indicating that the peer is
1310 * being unpaired
1311 * @param params Subscription parameters.
1312 * @param data Attribute value data. If NULL then subscription was removed.
1313 * @param length Attribute value length.
1314 *
1315 * @return BT_GATT_ITER_CONTINUE to continue receiving value notifications.
1316 * BT_GATT_ITER_STOP to unsubscribe from value notifications.
1317 */
1318 typedef u8_t (*bt_gatt_notify_func_t)(struct bt_conn *conn,
1319 struct bt_gatt_subscribe_params *params,
1320 const void *data, u16_t length);
1321
1322 /** Subscription flags */
1323 enum {
1324 /** @brief Persistence flag
1325 *
1326 * If set, indicates that the subscription is not saved
1327 * on the GATT server side. Therefore, upon disconnection,
1328 * the subscription will be automatically removed
1329 * from the client's subscriptions list and
1330 * when the client reconnects, it will have to
1331 * issue a new subscription.
1332 */
1333 BT_GATT_SUBSCRIBE_FLAG_VOLATILE,
1334
1335 /** @brief No resubscribe flag
1336 *
1337 * By default when BT_GATT_SUBSCRIBE_FLAG_VOLATILE is unset, the
1338 * subscription will be automatically renewed when the client
1339 * reconnects, as a workaround for GATT servers that do not persist
1340 * subscriptions.
1341 *
1342 * This flag will disable the automatic resubscription. It is useful
1343 * if the application layer knows that the GATT server remembers
1344 * subscriptions from previous connections and wants to avoid renewing
1345 * the subscriptions.
1346 */
1347 BT_GATT_SUBSCRIBE_FLAG_NO_RESUB,
1348
1349 /** @brief Write pending flag
1350 *
1351 * If set, indicates write operation is pending waiting remote end to
1352 * respond.
1353 */
1354 BT_GATT_SUBSCRIBE_FLAG_WRITE_PENDING,
1355
1356 BT_GATT_SUBSCRIBE_NUM_FLAGS
1357 };
1358
1359 /** @brief GATT Subscribe parameters */
1360 struct bt_gatt_subscribe_params {
1361 /** Notification value callback */
1362 bt_gatt_notify_func_t notify;
1363 /** Subscribe value handle */
1364 u16_t value_handle;
1365 /** Subscribe CCC handle */
1366 u16_t ccc_handle;
1367 /** Subscribe value */
1368 u16_t value;
1369 /** Subscription flags */
1370 ATOMIC_DEFINE(flags, BT_GATT_SUBSCRIBE_NUM_FLAGS);
1371
1372 sys_snode_t node;
1373 };
1374
1375 /** @brief Subscribe Attribute Value Notification
1376 *
1377 * This procedure subscribe to value notification using the Client
1378 * Characteristic Configuration handle.
1379 * If notification received subscribe value callback is called to return
1380 * notified value. One may then decide whether to unsubscribe directly from
1381 * this callback. Notification callback with NULL data will not be called if
1382 * subscription was removed by this method.
1383 *
1384 * @note This procedure is asynchronous therefore the parameters need to
1385 * remains valid while it is active.
1386 *
1387 * @param conn Connection object.
1388 * @param params Subscribe parameters.
1389 *
1390 * @return 0 in case of success or negative value in case of error.
1391 */
1392 int bt_gatt_subscribe(struct bt_conn *conn,
1393 struct bt_gatt_subscribe_params *params);
1394
1395 /** @brief Unsubscribe Attribute Value Notification
1396 *
1397 * This procedure unsubscribe to value notification using the Client
1398 * Characteristic Configuration handle. Notification callback with NULL data
1399 * will be called if subscription was removed by this call, until then the
1400 * parameters cannot be reused.
1401 *
1402 * @param conn Connection object.
1403 * @param params Subscribe parameters.
1404 *
1405 * @return 0 in case of success or negative value in case of error.
1406 */
1407 int bt_gatt_unsubscribe(struct bt_conn *conn,
1408 struct bt_gatt_subscribe_params *params);
1409
1410 /** @brief Cancel GATT pending request
1411 *
1412 * @param conn Connection object.
1413 * @param params Requested params address.
1414 */
1415 void bt_gatt_cancel(struct bt_conn *conn, void *params);
1416
1417 /** @} */
1418
1419 #ifdef __cplusplus
1420 }
1421 #endif
1422
1423 /**
1424 * @}
1425 */
1426
1427 #endif /* __BT_GATT_H */
1428