Line data Source code
1 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 ZEPHYR_INCLUDE_BLUETOOTH_GATT_H_
11 : #define ZEPHYR_INCLUDE_BLUETOOTH_GATT_H_
12 :
13 : /**
14 : * @brief Generic Attribute Profile (GATT)
15 : * @details The GATT layer manages the service database by providing APIs for
16 : * service registration and attribute declaration. For more
17 : * information, see @ref bt_gatt_client and @ref bt_gatt_server.
18 : * @defgroup bt_gatt Generic Attribute Profile (GATT)
19 : * @ingroup bluetooth
20 : * @{
21 : */
22 :
23 : #include <stdint.h>
24 : #include <stddef.h>
25 : #include <string.h>
26 :
27 : #include <sys/types.h>
28 :
29 : #include <zephyr/autoconf.h>
30 : #include <zephyr/bluetooth/addr.h>
31 : #include <zephyr/bluetooth/conn.h>
32 : #include <zephyr/bluetooth/uuid.h>
33 : #include <zephyr/bluetooth/att.h>
34 : #include <zephyr/sys/atomic.h>
35 : #include <zephyr/sys/iterable_sections.h>
36 : #include <zephyr/sys/slist.h>
37 : #include <zephyr/sys/util.h>
38 : #include <zephyr/sys/util_macro.h>
39 : #include <zephyr/toolchain.h>
40 :
41 : #ifdef __cplusplus
42 : extern "C" {
43 : #endif
44 :
45 : /** GATT attribute permission bit field values */
46 1 : enum bt_gatt_perm {
47 : /** No operations supported, e.g. for notify-only */
48 : BT_GATT_PERM_NONE = 0,
49 :
50 : /** Attribute read permission. */
51 : BT_GATT_PERM_READ = BIT(0),
52 :
53 : /** Attribute write permission. */
54 : BT_GATT_PERM_WRITE = BIT(1),
55 :
56 : /** @brief Attribute read permission with encryption.
57 : *
58 : * If set, requires encryption for read access.
59 : */
60 : BT_GATT_PERM_READ_ENCRYPT = BIT(2),
61 :
62 : /** @brief Attribute write permission with encryption.
63 : *
64 : * If set, requires encryption for write access.
65 : */
66 : BT_GATT_PERM_WRITE_ENCRYPT = BIT(3),
67 :
68 : /** @brief Attribute read permission with authentication.
69 : *
70 : * If set, requires encryption using authenticated link-key for read
71 : * access.
72 : */
73 : BT_GATT_PERM_READ_AUTHEN = BIT(4),
74 :
75 : /** @brief Attribute write permission with authentication.
76 : *
77 : * If set, requires encryption using authenticated link-key for write
78 : * access.
79 : */
80 : BT_GATT_PERM_WRITE_AUTHEN = BIT(5),
81 :
82 : /** @brief Attribute prepare write permission.
83 : *
84 : * If set, allows prepare writes with use of ``BT_GATT_WRITE_FLAG_PREPARE``
85 : * passed to write callback.
86 : */
87 : BT_GATT_PERM_PREPARE_WRITE = BIT(6),
88 :
89 : /** @brief Attribute read permission with LE Secure Connection encryption.
90 : *
91 : * If set, requires that LE Secure Connections is used for read access.
92 : */
93 : BT_GATT_PERM_READ_LESC = BIT(7),
94 :
95 : /** @brief Attribute write permission with LE Secure Connection encryption.
96 : *
97 : * If set, requires that LE Secure Connections is used for write access.
98 : */
99 : BT_GATT_PERM_WRITE_LESC = BIT(8),
100 : };
101 :
102 : /**
103 : * @brief Construct error return value for attribute read and write callbacks.
104 : *
105 : * @param _att_err ATT error code
106 : *
107 : * @return Appropriate error code for the attribute callbacks.
108 : */
109 1 : #define BT_GATT_ERR(_att_err) (-(_att_err))
110 :
111 : /** GATT attribute write flags */
112 1 : enum bt_gatt_attr_write_flag {
113 : /** @brief Attribute prepare write flag
114 : *
115 : * If set, write callback should only check if the device is
116 : * authorized but no data shall be written.
117 : */
118 : BT_GATT_WRITE_FLAG_PREPARE = BIT(0),
119 :
120 : /** @brief Attribute write command flag
121 : *
122 : * If set, indicates that write operation is a command (Write without
123 : * response) which doesn't generate any response.
124 : */
125 : BT_GATT_WRITE_FLAG_CMD = BIT(1),
126 :
127 : /** @brief Attribute write execute flag
128 : *
129 : * If set, indicates that write operation is a execute, which indicates
130 : * the end of a long write, and will come after 1 or more
131 : * @ref BT_GATT_WRITE_FLAG_PREPARE.
132 : */
133 : BT_GATT_WRITE_FLAG_EXECUTE = BIT(2),
134 : };
135 :
136 : /* Forward declaration of GATT Attribute structure */
137 : struct bt_gatt_attr;
138 :
139 : /** @typedef bt_gatt_attr_read_func_t
140 : * @brief Attribute read callback
141 : *
142 : * This is the type of the bt_gatt_attr.read() method.
143 : *
144 : * This function may safely assume the Attribute Permissions
145 : * are satisfied for this read. Callers are responsible for
146 : * this.
147 : *
148 : * Callers may set @p conn to emulate a GATT client read, or
149 : * leave it NULL for local reads.
150 : *
151 : * @note GATT server relies on this method to handle read
152 : * operations from remote GATT clients. But this method is not
153 : * reserved for the GATT server. E.g. You can lookup attributes
154 : * in the local ATT database and invoke this method.
155 : *
156 : * @note The GATT server propagates the return value from this
157 : * method back to the remote client.
158 : *
159 : * @param conn The connection that is requesting to read.
160 : * NULL if local.
161 : * @param attr The attribute that's being read
162 : * @param buf Buffer to place the read result in
163 : * @param len Length of data to read
164 : * @param offset Offset to start reading from
165 : *
166 : * @return Number of bytes read, or in case of an error
167 : * ``BT_GATT_ERR()`` with a specific ``BT_ATT_ERR_*`` error code.
168 : */
169 1 : typedef ssize_t (*bt_gatt_attr_read_func_t)(struct bt_conn *conn,
170 : const struct bt_gatt_attr *attr,
171 : void *buf, uint16_t len,
172 : uint16_t offset);
173 :
174 : /** @typedef bt_gatt_attr_write_func_t
175 : * @brief Attribute Value write implementation
176 : *
177 : * This is the type of the bt_gatt_attr.write() method.
178 : *
179 : * This function may safely assume the Attribute Permissions
180 : * are satisfied for this write. Callers are responsible for
181 : * this.
182 : *
183 : * Callers may set @p conn to emulate a GATT client write, or
184 : * leave it NULL for local writes.
185 : *
186 : * If @p flags contains @ref BT_GATT_WRITE_FLAG_PREPARE, then
187 : * the method shall not perform a write, but instead only check
188 : * if the write is authorized and return an error code if not.
189 : *
190 : * Attribute Value write implementations can and often do have
191 : * side effects besides potentially storing the value. E.g.
192 : * togging an LED.
193 : *
194 : * @note GATT server relies on this method to handle write
195 : * operations from remote GATT clients. But this method is not
196 : * reserved for the GATT server. E.g. You can lookup attributes
197 : * in the local ATT database and invoke this method.
198 : *
199 : * @note The GATT server propagates the return value from this
200 : * method back to the remote client.
201 : *
202 : * @param conn The connection that is requesting to write
203 : * @param attr The attribute that's being written
204 : * @param buf Buffer with the data to write
205 : * @param len Number of bytes in the buffer
206 : * @param offset Offset to start writing from
207 : * @param flags Flags of type @ref bt_gatt_attr_write_flag
208 : *
209 : * @return Number of bytes written, or in case of an error
210 : * ``BT_GATT_ERR()`` with a specific ``BT_ATT_ERR_*`` error code.
211 : */
212 1 : typedef ssize_t (*bt_gatt_attr_write_func_t)(struct bt_conn *conn,
213 : const struct bt_gatt_attr *attr,
214 : const void *buf, uint16_t len,
215 : uint16_t offset, uint8_t flags);
216 :
217 : /** @brief GATT Attribute
218 : *
219 : * This type primarily represents an ATT Attribute that may be
220 : * an entry in the local ATT database. The objects of this type
221 : * must be part of an array that forms a GATT service.
222 : *
223 : * While the formed GATT service is registered with the local
224 : * GATT server, pointers to this type can typically be given to
225 : * GATT server APIs, like bt_gatt_notify().
226 : */
227 1 : struct bt_gatt_attr {
228 : /** @brief Attribute Type
229 : *
230 : * The Attribute Type is a UUID which determines the interface that can
231 : * be expected from the read() and write() methods and
232 : * the possible permission configurations.
233 : *
234 : * E.g. Attribute of type @ref BT_UUID_GATT_CPF will act as a
235 : * GATT Characteristic Presentation Format descriptor as
236 : * specified in Core Specification 3.G.3.3.3.5.
237 : *
238 : * You can define a new Attribute Type for your application specific
239 : * use by generating a new UUID for it.
240 : */
241 1 : const struct bt_uuid *uuid;
242 :
243 : /** @brief Attribute Value read method
244 : *
245 : * Readable Attributes must implement this method.
246 : *
247 : * Must be NULL if the attribute is not readable.
248 : *
249 : * The behavior of this method is determined by the Attribute
250 : * Type.
251 : *
252 : * See @ref bt_gatt_attr_read_func_t.
253 : */
254 1 : bt_gatt_attr_read_func_t read;
255 :
256 : /** @brief Attribute Value write method
257 : *
258 : * Writeable Attributes must implement this method.
259 : *
260 : * Must be NULL if the attribute is not writable.
261 : *
262 : * The behavior of this method is determined by the Attribute
263 : * Type.
264 : *
265 : * See @ref bt_gatt_attr_write_func_t.
266 : */
267 1 : bt_gatt_attr_write_func_t write;
268 :
269 : /** @brief Private data for read() and write() implementation
270 : *
271 : * The meaning of this field varies and is not specified here.
272 : *
273 : * @note Attributes may have the same Attribute Type but have
274 : * different implementations, with incompatible user data.
275 : * Attribute Type alone must not be used to infer the type of
276 : * the user data.
277 : *
278 : * @sa bt_gatt_discover_func_t about this field.
279 : */
280 1 : void *user_data;
281 :
282 : /** @brief Attribute Handle
283 : *
284 : * The Attribute Handle is an index corresponding to a specific
285 : * Attribute in the ATT database.
286 : *
287 : * @note Use bt_gatt_attr_get_handle() for attributes in the
288 : * local ATT database.
289 : */
290 1 : uint16_t handle;
291 :
292 : /** @brief Attribute Permissions
293 : *
294 : * Bit field of @ref bt_gatt_perm.
295 : *
296 : * The permissions are security requirements that must be
297 : * satisfied before calling read() or write().
298 : */
299 1 : uint16_t perm: 15;
300 :
301 : /** @cond INTERNAL_HIDDEN
302 : * Indicates if the attribute handle was assigned automatically.
303 : *
304 : * This flag is set to 1 if the attribute handle was assigned by the stack,
305 : * and 0 if it was manually set by the application.
306 : *
307 : * @note Applications must not modify this field.
308 : */
309 : bool _auto_assigned_handle: 1;
310 : /** @endcond */
311 : };
312 :
313 : /** @brief Static GATT Service structure
314 : *
315 : * Allows the user the declare static GATT Services with the aim of reducing the
316 : * used RAM. The @ref BT_GATT_SERVICE_DEFINE macro can be used to statically
317 : * define and register a service.
318 : */
319 1 : struct bt_gatt_service_static {
320 : /** Service Attributes */
321 1 : const struct bt_gatt_attr *attrs;
322 : /** Service Attribute count */
323 1 : size_t attr_count;
324 : };
325 :
326 : /** @brief GATT Service structure
327 : *
328 : * This structure is used to define GATT services which can be registered and
329 : * unregistered at runtime. See @ref bt_gatt_service_register for when services
330 : * should be registered.
331 : */
332 1 : struct bt_gatt_service {
333 : /** Service Attributes */
334 1 : struct bt_gatt_attr *attrs;
335 : /** Service Attribute count */
336 1 : size_t attr_count;
337 : /** @cond INTERNAL_HIDDEN
338 : * Field used for list handling.
339 : */
340 : sys_snode_t node;
341 : /** @endcond */
342 : };
343 :
344 : /** @brief Service Attribute Value.
345 : *
346 : * This is the data described by the Attribute Type and indexed by the
347 : * Attribute Handle in the database.
348 : */
349 1 : struct bt_gatt_service_val {
350 : /** Service UUID. */
351 1 : const struct bt_uuid *uuid;
352 : /** Handle of the last Attribute within the Service. */
353 1 : uint16_t end_handle;
354 : };
355 :
356 : /** @brief Include Attribute Value.
357 : *
358 : * This structure represents an included service attribute in the GATT
359 : * server. An included service is a service that is referenced within another
360 : * service, allowing for the reuse of common service definitions.
361 : */
362 1 : struct bt_gatt_include {
363 : /** Service UUID. */
364 1 : const struct bt_uuid *uuid;
365 : /** Handle of the first attribute within the included service. */
366 1 : uint16_t start_handle;
367 : /** Handle of the last attribute within the included service. */
368 1 : uint16_t end_handle;
369 : };
370 :
371 : /** @brief GATT callback structure. */
372 1 : struct bt_gatt_cb {
373 : /** @brief The maximum ATT MTU on a connection has changed.
374 : *
375 : * This callback notifies the application that the maximum TX or RX
376 : * ATT MTU has increased.
377 : *
378 : * @param conn Connection object.
379 : * @param tx Updated TX ATT MTU.
380 : * @param rx Updated RX ATT MTU.
381 : */
382 1 : void (*att_mtu_updated)(struct bt_conn *conn, uint16_t tx, uint16_t rx);
383 :
384 : /** @cond INTERNAL_HIDDEN
385 : * Field used for list handling.
386 : */
387 : sys_snode_t node;
388 : /** @endcond */
389 : };
390 :
391 : /** @brief GATT authorization callback structure. */
392 1 : struct bt_gatt_authorization_cb {
393 : /** @brief Authorize the GATT read operation.
394 : *
395 : * This callback allows the application to authorize the GATT
396 : * read operation for the attribute that is being read.
397 : *
398 : * @param conn Connection object.
399 : * @param attr The attribute that is being read.
400 : *
401 : * @retval true Authorize the operation and allow it to execute.
402 : * @retval false Reject the operation and prevent it from executing.
403 : */
404 1 : bool (*read_authorize)(struct bt_conn *conn,
405 : const struct bt_gatt_attr *attr);
406 :
407 : /** @brief Authorize the GATT write operation.
408 : *
409 : * This callback allows the application to authorize the GATT
410 : * write operation for the attribute that is being written.
411 : *
412 : * @param conn Connection object.
413 : * @param attr The attribute that is being written.
414 : *
415 : * @retval true Authorize the operation and allow it to execute.
416 : * @retval false Reject the operation and prevent it from executing.
417 : */
418 1 : bool (*write_authorize)(struct bt_conn *conn,
419 : const struct bt_gatt_attr *attr);
420 : };
421 :
422 : /** Characteristic Properties Bit field values */
423 :
424 : /**
425 : * @brief Characteristic broadcast property.
426 : *
427 : * If set, permits broadcasts of the Characteristic Value using Server
428 : * Characteristic Configuration Descriptor.
429 : */
430 1 : #define BT_GATT_CHRC_BROADCAST 0x01
431 : /**
432 : * @brief Characteristic read property.
433 : *
434 : * If set, permits reads of the Characteristic Value.
435 : */
436 1 : #define BT_GATT_CHRC_READ 0x02
437 : /**
438 : * @brief Characteristic write without response property.
439 : *
440 : * If set, permits write of the Characteristic Value without response.
441 : */
442 1 : #define BT_GATT_CHRC_WRITE_WITHOUT_RESP 0x04
443 : /**
444 : * @brief Characteristic write with response property.
445 : *
446 : * If set, permits write of the Characteristic Value with response.
447 : */
448 1 : #define BT_GATT_CHRC_WRITE 0x08
449 : /**
450 : * @brief Characteristic notify property.
451 : *
452 : * If set, permits notifications of a Characteristic Value without
453 : * acknowledgment.
454 : */
455 1 : #define BT_GATT_CHRC_NOTIFY 0x10
456 : /**
457 : * @brief Characteristic indicate property.
458 : *
459 : * If set, permits indications of a Characteristic Value with acknowledgment.
460 : */
461 1 : #define BT_GATT_CHRC_INDICATE 0x20
462 : /**
463 : * @brief Characteristic Authenticated Signed Writes property.
464 : *
465 : * If set, permits signed writes to the Characteristic Value.
466 : */
467 1 : #define BT_GATT_CHRC_AUTH 0x40
468 : /**
469 : * @brief Characteristic Extended Properties property.
470 : *
471 : * If set, additional characteristic properties are defined in the
472 : * Characteristic Extended Properties Descriptor.
473 : */
474 1 : #define BT_GATT_CHRC_EXT_PROP 0x80
475 :
476 : /** @brief Attribute Value of a Characteristic Declaration.
477 : *
478 : * This is the data associated with the characteristic, and can be read from or
479 : * written to by a GATT client depending on the characteristic properties.
480 : */
481 1 : struct bt_gatt_chrc {
482 : /** Characteristic UUID. */
483 1 : const struct bt_uuid *uuid;
484 : /** Characteristic Value handle. */
485 1 : uint16_t value_handle;
486 : /** Characteristic properties, a bitmap of ``BT_GATT_CHRC_*`` macros. */
487 1 : uint8_t properties;
488 : };
489 :
490 : /** Characteristic Extended Properties Bit field values */
491 1 : #define BT_GATT_CEP_RELIABLE_WRITE 0x0001
492 0 : #define BT_GATT_CEP_WRITABLE_AUX 0x0002
493 :
494 : /** @brief Characteristic Extended Properties Attribute Value.
495 : *
496 : * Used in the discovery of standard characteristic descriptor values. Shall
497 : * exist if the @ref BT_GATT_CHRC_EXT_PROP bit is set in the characteristic
498 : * properties. Can be used with the @ref BT_GATT_CEP macro to declare the CEP
499 : * descriptor.
500 : */
501 1 : struct bt_gatt_cep {
502 : /** Characteristic Extended properties, a bitmap of ``BT_GATT_CEP_*`` macros. */
503 1 : uint16_t properties;
504 : };
505 :
506 : /** Client Characteristic Configuration Values */
507 :
508 : /**
509 : * @brief Client Characteristic Configuration Notification.
510 : *
511 : * If set, changes to Characteristic Value shall be notified.
512 : */
513 1 : #define BT_GATT_CCC_NOTIFY 0x0001
514 : /**
515 : * @brief Client Characteristic Configuration Indication.
516 : *
517 : * If set, changes to Characteristic Value shall be indicated.
518 : */
519 1 : #define BT_GATT_CCC_INDICATE 0x0002
520 :
521 : /** @brief Client Characteristic Configuration Attribute Value
522 : *
523 : * Used in the discovery of standard characteristic descriptor values.
524 : */
525 1 : struct bt_gatt_ccc {
526 : /** Client Characteristic Configuration flags, a bitmap of ``BT_GATT_CCC_*`` macros. */
527 1 : uint16_t flags;
528 : };
529 :
530 : /** Server Characteristic Configuration Values */
531 :
532 : /**
533 : * @brief Server Characteristic Configuration Broadcast
534 : *
535 : * If set, the characteristic value shall be broadcast in the advertising data
536 : * when the server is advertising.
537 : */
538 1 : #define BT_GATT_SCC_BROADCAST 0x0001
539 :
540 : /** @brief Server Characteristic Configuration Attribute Value
541 : *
542 : * Used in the discovery of standard characteristic descriptor values.
543 : */
544 1 : struct bt_gatt_scc {
545 : /** Server Characteristic Configuration flags, a bitmap of ``BT_GATT_SCC_*`` macros. */
546 1 : uint16_t flags;
547 : };
548 :
549 : /** @brief GATT Characteristic Presentation Format Attribute Value.
550 : *
551 : * Used in the discovery of standard characteristic descriptor values. Can be
552 : * used with the @ref BT_GATT_CPF macro to declare the CPF descriptor.
553 : */
554 1 : struct bt_gatt_cpf {
555 : /** @brief Format of the value of the characteristic.
556 : *
557 : * The format types can be found in section 2.4.1 of the Bluetooth SIG
558 : * Assigned Numbers document.
559 : */
560 1 : uint8_t format;
561 : /** @brief Exponent field for value formatting.
562 : *
563 : * Only used on integer format types.
564 : * actual value = Characteristic Value x 10^Exponent
565 : */
566 1 : int8_t exponent;
567 : /** @brief UUID of the unit of the characteristic.
568 : *
569 : * The units can be found in section 3.5 of the Bluetooth SIG Assigned
570 : * Numbers document.
571 : */
572 1 : uint16_t unit;
573 : /** @brief Name space of the description.
574 : *
575 : * Used to identify the organization that is responsible for defining
576 : * the enumerations for the description field. See section 2.4.2 of the
577 : * Bluetooth SIG Assigned Numbers document.
578 : */
579 1 : uint8_t name_space;
580 : /** @brief Description of the characteristic as defined in a higher layer profile.
581 : *
582 : * An enumerated value defined by the organization identified by the
583 : * name_space field. See section 2.4.2.1 of the Bluetooth SIG Assigned
584 : * Numbers document.
585 : */
586 1 : uint16_t description;
587 : };
588 :
589 : /**
590 : * @defgroup bt_gatt_server GATT Server APIs
591 : * @ingroup bt_gatt
592 : * @{
593 : */
594 :
595 : /** Converts a GATT error to string.
596 : *
597 : * The GATT errors are created with @ref BT_GATT_ERR.
598 : *
599 : * The error codes are described in the Bluetooth Core specification,
600 : * Vol 3, Part F, Section 3.4.1.1.
601 : *
602 : * The ATT and GATT documentation found in Vol 4, Part F and
603 : * Part G describe when the different error codes are used.
604 : *
605 : * See also the defined BT_ATT_ERR_* macros.
606 : *
607 : * @return The string representation of the GATT error code.
608 : * If @kconfig{CONFIG_BT_ATT_ERR_TO_STR} is not enabled,
609 : * this just returns the empty string.
610 : */
611 1 : static inline const char *bt_gatt_err_to_str(int gatt_err)
612 : {
613 : return bt_att_err_to_str((gatt_err) < 0 ? -(gatt_err) : (gatt_err));
614 : }
615 :
616 : /** @brief Register GATT callbacks.
617 : *
618 : * Register callbacks to monitor the state of GATT. The callback struct
619 : * must remain valid for the remainder of the program.
620 : *
621 : * @param cb Callback struct.
622 : */
623 1 : void bt_gatt_cb_register(struct bt_gatt_cb *cb);
624 :
625 : /** @brief Register GATT authorization callbacks.
626 : *
627 : * Register callbacks to perform application-specific authorization of GATT
628 : * operations on all registered GATT attributes. The callback structure must
629 : * remain valid throughout the entire duration of the Bluetooth subsys
630 : * activity.
631 : *
632 : * The @kconfig{CONFIG_BT_GATT_AUTHORIZATION_CUSTOM} Kconfig must be enabled
633 : * to make this API functional.
634 : *
635 : * This API allows the user to register only one callback structure
636 : * concurrently. Passing NULL unregisters the previous set of callbacks
637 : * and makes it possible to register a new one.
638 : *
639 : * @param cb Callback struct.
640 : *
641 : * @return Zero on success or negative error code otherwise.
642 : */
643 1 : int bt_gatt_authorization_cb_register(const struct bt_gatt_authorization_cb *cb);
644 :
645 : /** @brief Register GATT service.
646 : *
647 : * To register a GATT service, applications can make use of macros such as
648 : * ``BT_GATT_PRIMARY_SERVICE``, ``BT_GATT_CHARACTERISTIC``,
649 : * ``BT_GATT_DESCRIPTOR``, etc.
650 : *
651 : * When using @kconfig{CONFIG_BT_SETTINGS} then all services that should have
652 : * bond configuration loaded, i.e. CCC values, must be registered before
653 : * calling @ref settings_load.
654 : *
655 : * When using @kconfig{CONFIG_BT_GATT_CACHING} and @kconfig{CONFIG_BT_SETTINGS}
656 : * then all services that should be included in the GATT Database Hash
657 : * calculation should be added before calling @ref settings_load.
658 : * All services registered after settings_load will trigger a new database hash
659 : * calculation and a new hash stored.
660 : *
661 : * There are two situations where this function can be called: either before
662 : * `bt_init()` has been called, or after `settings_load()` has been called.
663 : * Registering a service in the middle is not supported and will return an
664 : * error.
665 : *
666 : * @param svc Service containing the available attributes
667 : *
668 : * @return 0 in case of success or negative value in case of error.
669 : * @return -EAGAIN if ``bt_init()`` has been called but ``settings_load()`` hasn't yet.
670 : */
671 1 : int bt_gatt_service_register(struct bt_gatt_service *svc);
672 :
673 : /** @brief Unregister GATT service.
674 : *
675 : * @param svc Service to be unregistered.
676 : *
677 : * @return 0 in case of success or negative value in case of error.
678 : */
679 1 : int bt_gatt_service_unregister(struct bt_gatt_service *svc);
680 :
681 : /** @brief Check if GATT service is registered.
682 : *
683 : * @param svc Service to be checked.
684 : *
685 : * @return true if registered or false if not register.
686 : */
687 1 : bool bt_gatt_service_is_registered(const struct bt_gatt_service *svc);
688 :
689 : /** @brief to be used as return values for @ref bt_gatt_attr_func_t and @ref bt_gatt_read_func_t
690 : * type callbacks.
691 : */
692 0 : enum bt_gatt_iter {
693 : BT_GATT_ITER_STOP = 0,
694 : BT_GATT_ITER_CONTINUE,
695 : };
696 :
697 : /** @typedef bt_gatt_attr_func_t
698 : * @brief Attribute iterator callback.
699 : *
700 : * @param attr Attribute found.
701 : * @param handle Attribute handle found.
702 : * @param user_data Data given.
703 : *
704 : * @return ``BT_GATT_ITER_CONTINUE`` if should continue to the next attribute.
705 : * @return ``BT_GATT_ITER_STOP`` to stop.
706 : */
707 1 : typedef uint8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr,
708 : uint16_t handle,
709 : void *user_data);
710 :
711 : /** @brief Attribute iterator by type.
712 : *
713 : * Iterate attributes in the given range matching given UUID and/or data.
714 : *
715 : * @param start_handle Start attribute handle.
716 : * @param end_handle End attribute handle. Often set to start_handle + attr_count or
717 : * BT_ATT_LAST_ATTRIBUTE_HANDLE.
718 : * @param uuid UUID to match, passing NULL skips UUID matching.
719 : * @param attr_data Attribute data to match, passing NULL skips data matching.
720 : * @param num_matches Number matches, passing 0 makes it unlimited.
721 : * @param func Callback function.
722 : * @param user_data Data to pass to the callback.
723 : */
724 1 : void bt_gatt_foreach_attr_type(uint16_t start_handle, uint16_t end_handle,
725 : const struct bt_uuid *uuid,
726 : const void *attr_data, uint16_t num_matches,
727 : bt_gatt_attr_func_t func,
728 : void *user_data);
729 :
730 : /** @brief Attribute iterator.
731 : *
732 : * Iterate attributes in the given range.
733 : *
734 : * @param start_handle Starting attribute handle.
735 : * @param end_handle Ending attribute handle.
736 : * @param func Callback function.
737 : * @param user_data Data to pass to the callback.
738 : */
739 1 : static inline void bt_gatt_foreach_attr(uint16_t start_handle, uint16_t end_handle,
740 : bt_gatt_attr_func_t func,
741 : void *user_data)
742 : {
743 : bt_gatt_foreach_attr_type(start_handle, end_handle, NULL, NULL, 0, func,
744 : user_data);
745 : }
746 :
747 : /** @brief Iterate to the next attribute
748 : *
749 : * Iterate to the next attribute following a given attribute.
750 : *
751 : * @param attr Current Attribute.
752 : *
753 : * @return The next attribute or NULL if it cannot be found.
754 : */
755 1 : struct bt_gatt_attr *bt_gatt_attr_next(const struct bt_gatt_attr *attr);
756 :
757 : /** @brief Find Attribute by UUID.
758 : *
759 : * Find the attribute with the matching UUID.
760 : * To limit the search to a service set the attr to the service attributes and
761 : * the ``attr_count`` to the service attribute count .
762 : *
763 : * @param attr Pointer to an attribute that serves as the starting point
764 : * for the search of a match for the UUID.
765 : * Passing NULL will search the entire range.
766 : * @param attr_count The number of attributes from the starting point to
767 : * search for a match for the UUID.
768 : * Set to 0 to search until the end.
769 : * @param uuid UUID to match.
770 : */
771 1 : struct bt_gatt_attr *bt_gatt_find_by_uuid(const struct bt_gatt_attr *attr,
772 : uint16_t attr_count,
773 : const struct bt_uuid *uuid);
774 :
775 : /** @brief Get Attribute handle.
776 : *
777 : * @param attr An attribute object currently registered in the
778 : * local ATT server.
779 : *
780 : * @return Handle of the corresponding attribute or zero if the attribute
781 : * could not be found.
782 : */
783 1 : uint16_t bt_gatt_attr_get_handle(const struct bt_gatt_attr *attr);
784 :
785 : /** @brief Get the handle of the characteristic value descriptor.
786 : *
787 : * @param attr A Characteristic Attribute.
788 : *
789 : * @note The ``user_data`` of the attribute must be of type @ref bt_gatt_chrc and the ``uuid`` shall
790 : * be BT_UUID_GATT_CHRC.
791 : *
792 : * @return the handle of the corresponding Characteristic Value. The value will
793 : * be zero (the invalid handle) if @p attr was not a characteristic
794 : * attribute.
795 : */
796 1 : uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr);
797 :
798 : /** @brief Generic Read Attribute value helper.
799 : *
800 : * Read attribute value from local database storing the result into buffer.
801 : *
802 : * @param conn Connection object.
803 : * @param attr Attribute to read.
804 : * @param buf Buffer to store the value.
805 : * @param buf_len Buffer length.
806 : * @param offset Start offset.
807 : * @param value Attribute value.
808 : * @param value_len Length of the attribute value.
809 : *
810 : * @return number of bytes read in case of success or negative values in
811 : * case of error.
812 : */
813 1 : ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr,
814 : void *buf, uint16_t buf_len, uint16_t offset,
815 : const void *value, uint16_t value_len);
816 :
817 : /** @brief Read Service Attribute helper.
818 : *
819 : * Read service attribute value from local database storing the result into
820 : * buffer after encoding it.
821 : * @note Only use this with attributes which ``user_data`` is a ``bt_uuid``.
822 : *
823 : * @param conn Connection object.
824 : * @param attr Attribute to read.
825 : * @param buf Buffer to store the value read.
826 : * @param len Buffer length.
827 : * @param offset Start offset.
828 : *
829 : * @return number of bytes read in case of success or negative values in
830 : * case of error.
831 : */
832 1 : ssize_t bt_gatt_attr_read_service(struct bt_conn *conn,
833 : const struct bt_gatt_attr *attr,
834 : void *buf, uint16_t len, uint16_t offset);
835 :
836 : /**
837 : * @brief Statically define and register a service.
838 : *
839 : * Helper macro to statically define and register a service.
840 : *
841 : * @param _name Service name.
842 : */
843 1 : #define BT_GATT_SERVICE_DEFINE(_name, ...) \
844 : const struct bt_gatt_attr attr_##_name[] = { __VA_ARGS__ }; \
845 : const STRUCT_SECTION_ITERABLE(bt_gatt_service_static, _name) = \
846 : BT_GATT_SERVICE(attr_##_name)
847 :
848 : #define _BT_GATT_ATTRS_ARRAY_DEFINE(n, _instances, _attrs_def) \
849 : static struct bt_gatt_attr attrs_##n[] = _attrs_def(_instances[n])
850 :
851 : #define _BT_GATT_SERVICE_ARRAY_ITEM(_n, _) BT_GATT_SERVICE(attrs_##_n)
852 :
853 : /**
854 : * @brief Statically define service structure array.
855 : *
856 : * Helper macro to statically define service structure array. Each element
857 : * of the array is linked to the service attribute array which is also
858 : * defined in this scope using ``_attrs_def`` macro.
859 : *
860 : * @param _name Name of service structure array.
861 : * @param _instances Array of instances to pass as user context to the
862 : * attribute callbacks.
863 : * @param _instance_num Number of elements in instance array.
864 : * @param _attrs_def Macro provided by the user that defines attribute
865 : * array for the service. This macro should accept single
866 : * parameter which is the instance context.
867 : */
868 : #define BT_GATT_SERVICE_INSTANCE_DEFINE( \
869 1 : _name, _instances, _instance_num, _attrs_def) \
870 : BUILD_ASSERT(ARRAY_SIZE(_instances) == _instance_num, \
871 : "The number of array elements does not match its size"); \
872 : LISTIFY(_instance_num, _BT_GATT_ATTRS_ARRAY_DEFINE, (;), \
873 : _instances, _attrs_def); \
874 : static struct bt_gatt_service _name[] = { \
875 : LISTIFY(_instance_num, _BT_GATT_SERVICE_ARRAY_ITEM, (,)) \
876 : }
877 :
878 : /**
879 : * @brief Service Structure Declaration Macro.
880 : *
881 : * Helper macro to declare a service structure.
882 : *
883 : * @param _attrs Service attributes.
884 : */
885 1 : #define BT_GATT_SERVICE(_attrs) \
886 : { \
887 : .attrs = _attrs, \
888 : .attr_count = ARRAY_SIZE(_attrs), \
889 : }
890 :
891 : /**
892 : * @brief Primary Service Declaration Macro.
893 : *
894 : * Helper macro to declare a primary service attribute.
895 : *
896 : * @param _service Service attribute value.
897 : */
898 1 : #define BT_GATT_PRIMARY_SERVICE(_service) \
899 : BT_GATT_ATTRIBUTE(BT_UUID_GATT_PRIMARY, BT_GATT_PERM_READ, \
900 : bt_gatt_attr_read_service, NULL, (void *)_service)
901 :
902 : /**
903 : * @brief Secondary Service Declaration Macro.
904 : *
905 : * Helper macro to declare a secondary service attribute.
906 : *
907 : * @note A secondary service is only intended to be included from a primary
908 : * service or another secondary service or other higher layer specification.
909 : *
910 : * @param _service Service attribute value.
911 : */
912 1 : #define BT_GATT_SECONDARY_SERVICE(_service) \
913 : BT_GATT_ATTRIBUTE(BT_UUID_GATT_SECONDARY, BT_GATT_PERM_READ, \
914 : bt_gatt_attr_read_service, NULL, (void *)_service)
915 :
916 : /** @brief Read Include Attribute helper.
917 : *
918 : * Read include service attribute value from local database storing the result
919 : * into buffer after encoding it.
920 : * @note Only use this with attributes which user_data is a ``bt_gatt_include``.
921 : * The function returns EINVAL if @p attr or @p attr->user_data is NULL.
922 : *
923 : * @param conn Connection object.
924 : * @param attr Attribute to read.
925 : * @param buf Buffer to store the value read.
926 : * @param len Buffer length.
927 : * @param offset Start offset.
928 : *
929 : * @return number of bytes read in case of success or negative values in
930 : * case of error.
931 : */
932 1 : ssize_t bt_gatt_attr_read_included(struct bt_conn *conn,
933 : const struct bt_gatt_attr *attr,
934 : void *buf, uint16_t len, uint16_t offset);
935 :
936 : /**
937 : * @brief Include Service Declaration Macro.
938 : *
939 : * Helper macro to declare database internal include service attribute.
940 : *
941 : * @param _service_incl the first service attribute of service to include
942 : */
943 1 : #define BT_GATT_INCLUDE_SERVICE(_service_incl) \
944 : BT_GATT_ATTRIBUTE(BT_UUID_GATT_INCLUDE, BT_GATT_PERM_READ, \
945 : bt_gatt_attr_read_included, NULL, _service_incl)
946 :
947 : /** @brief Read Characteristic Attribute helper.
948 : *
949 : * Read characteristic attribute value from local database storing the result
950 : * into buffer after encoding it.
951 : * @note Only use this with attributes which ``user_data`` is a ``bt_gatt_chrc``.
952 : *
953 : * @param conn Connection object.
954 : * @param attr Attribute to read.
955 : * @param buf Buffer to store the value read.
956 : * @param len Buffer length.
957 : * @param offset Start offset.
958 : *
959 : * @return number of bytes read in case of success or negative values in
960 : * case of error.
961 : */
962 1 : ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn,
963 : const struct bt_gatt_attr *attr, void *buf,
964 : uint16_t len, uint16_t offset);
965 :
966 : /** @brief Gatt Characteristic Initialization Macro.
967 : *
968 : * Helper macro used within the @ref BT_GATT_CHARACTERISTIC macro in the GATT attribute declaration
969 : * to set the attribute user data.
970 : *
971 : * @param _uuid Characteristic attribute uuid.
972 : * @param _handle Characcteristic attribute handle at init.
973 : * @param _props Characteristic attribute properties,
974 : * a bitmap of ``BT_GATT_CHRC_*`` macros.
975 : */
976 1 : #define BT_GATT_CHRC_INIT(_uuid, _handle, _props) \
977 : { \
978 : .uuid = _uuid, \
979 : .value_handle = _handle, \
980 : .properties = _props, \
981 : }
982 :
983 : /**
984 : * @brief Characteristic and Value Declaration Macro.
985 : *
986 : * Helper macro to declare a characteristic attribute along with its
987 : * attribute value.
988 : *
989 : * @param _uuid Characteristic attribute uuid.
990 : * @param _props Characteristic attribute properties,
991 : * a bitmap of ``BT_GATT_CHRC_*`` macros.
992 : * @param _perm Characteristic Attribute access permissions,
993 : * a bitmap of @ref bt_gatt_perm values.
994 : * @param _read Characteristic Attribute read callback
995 : * (@ref bt_gatt_attr_read_func_t).
996 : * @param _write Characteristic Attribute write callback
997 : * (@ref bt_gatt_attr_write_func_t).
998 : * @param _user_data Characteristic Attribute user data.
999 : */
1000 1 : #define BT_GATT_CHARACTERISTIC(_uuid, _props, _perm, _read, _write, _user_data) \
1001 : BT_GATT_ATTRIBUTE(BT_UUID_GATT_CHRC, BT_GATT_PERM_READ, \
1002 : bt_gatt_attr_read_chrc, NULL, \
1003 : ((struct bt_gatt_chrc[]) { \
1004 : BT_GATT_CHRC_INIT(_uuid, 0U, _props), \
1005 : })), \
1006 : BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _user_data)
1007 :
1008 : /**
1009 : * @brief BT_GATT_CCC_MAX is defined depending on whether
1010 : * @kconfig{CONFIG_BT_SETTINGS_CCC_LAZY_LOADING} or @kconfig{CONFIG_BT_CONN} is set.
1011 : *
1012 : * @kconfig{CONFIG_BT_SETTINGS_CCC_LAZY_LOADING} will set BT_GATT_CCC_MAX to
1013 : * @kconfig{CONFIG_BT_MAX_CONN}
1014 : * @kconfig{CONFIG_BT_CONN} will set BT_GATT_CCC_MAX to @kconfig{CONFIG_BT_MAX_PAIRED} +
1015 : * @kconfig{CONFIG_BT_MAX_CONN}
1016 : * If neither are set, BT_GATT_CCC_MAX is 0.
1017 : *
1018 : */
1019 : #if defined(CONFIG_BT_SETTINGS_CCC_LAZY_LOADING)
1020 : #define BT_GATT_CCC_MAX (CONFIG_BT_MAX_CONN)
1021 : #elif defined(CONFIG_BT_CONN)
1022 : #define BT_GATT_CCC_MAX (CONFIG_BT_MAX_PAIRED + CONFIG_BT_MAX_CONN)
1023 : #else
1024 1 : #define BT_GATT_CCC_MAX 0
1025 : #endif
1026 :
1027 : /** @brief GATT CCC configuration entry.
1028 : *
1029 : * bt_gatt_ccc_cfg is used within @ref bt_gatt_attr_read_ccc and @ref bt_gatt_attr_write_ccc to
1030 : * read and write the ccc configurations respectively.
1031 : *
1032 : */
1033 1 : struct bt_gatt_ccc_cfg {
1034 : /** Local identity, BT_ID_DEFAULT in most cases. */
1035 1 : uint8_t id;
1036 : /** Remote peer address. */
1037 1 : bt_addr_le_t peer;
1038 : /** @brief Configuration value
1039 : * Value used to enable or disable notifications or indications for a specific
1040 : * characteristic.
1041 : */
1042 1 : uint16_t value;
1043 : };
1044 :
1045 : /** Macro to keep old name for deprecation period. */
1046 : #define _bt_gatt_ccc bt_gatt_ccc_managed_user_data __DEPRECATED_MACRO
1047 :
1048 : /** @brief Internal representation of CCC value.
1049 : *
1050 : * @note Only use this as an argument for @ref BT_GATT_CCC_MANAGED
1051 : */
1052 1 : struct bt_gatt_ccc_managed_user_data {
1053 : /** Configuration for each connection */
1054 1 : struct bt_gatt_ccc_cfg cfg[BT_GATT_CCC_MAX];
1055 :
1056 : /** Highest value of all connected peer's subscriptions */
1057 1 : uint16_t value;
1058 :
1059 : /** @brief CCC attribute changed callback
1060 : *
1061 : * @param attr The attribute that's changed value
1062 : * @param value New value
1063 : */
1064 1 : void (*cfg_changed)(const struct bt_gatt_attr *attr, uint16_t value);
1065 :
1066 : /** @brief CCC attribute write validation callback
1067 : *
1068 : * @param conn The connection that is requesting to write
1069 : * @param attr The attribute that's being written
1070 : * @param value CCC value to write
1071 : *
1072 : * @return Number of bytes to write, or in case of an error
1073 : * BT_GATT_ERR() with a specific error code.
1074 : */
1075 1 : ssize_t (*cfg_write)(struct bt_conn *conn,
1076 : const struct bt_gatt_attr *attr, uint16_t value);
1077 :
1078 : /** @brief CCC attribute match handler
1079 : *
1080 : * Indicate if it is OK to send a notification or indication
1081 : * to the subscriber.
1082 : *
1083 : * @param conn The connection that is being checked
1084 : * @param attr The attribute that's being checked
1085 : *
1086 : * @return true if application has approved notification/indication,
1087 : * false if application does not approve.
1088 : */
1089 1 : bool (*cfg_match)(struct bt_conn *conn,
1090 : const struct bt_gatt_attr *attr);
1091 : };
1092 :
1093 : /** @brief Read Client Characteristic Configuration Attribute helper.
1094 : *
1095 : * Read CCC attribute value from local database storing the result into buffer
1096 : * after encoding it.
1097 : *
1098 : * @param conn Connection object.
1099 : * @param attr Attribute to read.
1100 : * @param buf Buffer to store the value read.
1101 : * @param len Buffer length.
1102 : * @param offset Start offset.
1103 : *
1104 : * @return number of bytes read in case of success or negative values in
1105 : * case of error.
1106 : */
1107 : /** @cond INTERNAL_HIDDEN
1108 : * @note Only use this with attributes which user_data is a bt_gatt_ccc_managed_user_data.
1109 : * @ref bt_gatt_ccc_managed_user_data being the internal representation of CCC value.
1110 : */
1111 : /** @endcond */
1112 1 : ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
1113 : const struct bt_gatt_attr *attr, void *buf,
1114 : uint16_t len, uint16_t offset);
1115 :
1116 : /** @brief Write Client Characteristic Configuration Attribute helper.
1117 : *
1118 : * Write value in the buffer into CCC attribute.
1119 : *
1120 : * @param conn Connection object.
1121 : * @param attr Attribute to read.
1122 : * @param buf Buffer to store the value read.
1123 : * @param len Buffer length.
1124 : * @param offset Start offset.
1125 : * @param flags Write flags, see @ref bt_gatt_attr_write_flag.
1126 : *
1127 : * @return number of bytes written in case of success or negative values in
1128 : * case of error.
1129 : */
1130 : /** @cond INTERNAL_HIDDEN
1131 : * @note Only use this with attributes which user_data is a bt_gatt_ccc_managed_user_data.
1132 : * @ref bt_gatt_ccc_managed_user_data being the internal representation of CCC value.
1133 : */
1134 : /** @endcond */
1135 1 : ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
1136 : const struct bt_gatt_attr *attr, const void *buf,
1137 : uint16_t len, uint16_t offset, uint8_t flags);
1138 :
1139 : /** Macro to keep old name for deprecation period. */
1140 1 : #define BT_GATT_CCC_INITIALIZER BT_GATT_CCC_MANAGED_USER_DATA_INIT __DEPRECATED_MACRO
1141 :
1142 : /**
1143 : * @brief Initialize Client Characteristic Configuration Declaration Macro.
1144 : *
1145 : * Helper macro to initialize a Managed CCC attribute value.
1146 : *
1147 : * @param _changed Configuration changed callback.
1148 : * @param _write Configuration write callback.
1149 : * @param _match Configuration match callback.
1150 : */
1151 1 : #define BT_GATT_CCC_MANAGED_USER_DATA_INIT(_changed, _write, _match) \
1152 : { \
1153 : .cfg = {}, \
1154 : .cfg_changed = _changed, \
1155 : .cfg_write = _write, \
1156 : .cfg_match = _match, \
1157 : }
1158 :
1159 : /**
1160 : * @brief Managed Client Characteristic Configuration Declaration Macro.
1161 : *
1162 : * Helper macro to declare a Managed CCC attribute.
1163 : *
1164 : * @param _ccc A new @ref bt_gatt_ccc_managed_user_data object with the same lifetime
1165 : * as the results of the call to BT_GATT_CCC_MANAGED.
1166 : * See the documentation of @ref bt_gatt_ccc_managed_user_data on how
1167 : * to initialize it.
1168 : * @param _perm CCC access permissions,
1169 : * a bitmap of @ref bt_gatt_perm values.
1170 : */
1171 1 : #define BT_GATT_CCC_MANAGED(_ccc, _perm) \
1172 : BT_GATT_ATTRIBUTE(BT_UUID_GATT_CCC, _perm, \
1173 : bt_gatt_attr_read_ccc, bt_gatt_attr_write_ccc, \
1174 : _ccc)
1175 :
1176 : /**
1177 : * @brief Client Characteristic Configuration Declaration Macro.
1178 : *
1179 : * Helper macro to declare a CCC attribute.
1180 : *
1181 : * @param _changed Configuration changed callback.
1182 : * @param _perm CCC access permissions,
1183 : * a bitmap of @ref bt_gatt_perm values.
1184 : */
1185 1 : #define BT_GATT_CCC(_changed, _perm) \
1186 : BT_GATT_CCC_MANAGED(((struct bt_gatt_ccc_managed_user_data[]){ \
1187 : BT_GATT_CCC_MANAGED_USER_DATA_INIT(_changed, NULL, NULL)}), \
1188 : _perm)
1189 :
1190 : /**
1191 : * @brief Client Characteristic Configuration Declaration Macro with write callback.
1192 : *
1193 : * Helper macro to declare a CCC attribute with a write callback.
1194 : *
1195 : * @param _changed Configuration changed callback.
1196 : * @param _write Configuration write callback.
1197 : * @param _perm CCC access permissions,
1198 : * a bitmap of @ref bt_gatt_perm values.
1199 : */
1200 1 : #define BT_GATT_CCC_WITH_WRITE_CB(_changed, _write, _perm) \
1201 : BT_GATT_CCC_MANAGED(((struct bt_gatt_ccc_managed_user_data[]){ \
1202 : BT_GATT_CCC_MANAGED_USER_DATA_INIT(_changed, _write, NULL)}), \
1203 : _perm)
1204 :
1205 : /** @brief Read Characteristic Extended Properties Attribute helper
1206 : *
1207 : * Read CEP attribute value from local database storing the result into buffer
1208 : * after encoding it.
1209 : *
1210 : * @note Only use this with attributes which user_data is a bt_gatt_cep.
1211 : *
1212 : * @param conn Connection object
1213 : * @param attr Attribute to read
1214 : * @param buf Buffer to store the value read
1215 : * @param len Buffer length
1216 : * @param offset Start offset
1217 : *
1218 : * @return number of bytes read in case of success or negative values in
1219 : * case of error.
1220 : */
1221 1 : ssize_t bt_gatt_attr_read_cep(struct bt_conn *conn,
1222 : const struct bt_gatt_attr *attr, void *buf,
1223 : uint16_t len, uint16_t offset);
1224 :
1225 : /**
1226 : * @brief Characteristic Extended Properties Declaration Macro.
1227 : *
1228 : * Helper macro to declare a CEP attribute.
1229 : *
1230 : * @param _value Pointer to a struct bt_gatt_cep.
1231 : */
1232 1 : #define BT_GATT_CEP(_value) \
1233 : BT_GATT_DESCRIPTOR(BT_UUID_GATT_CEP, BT_GATT_PERM_READ, \
1234 : bt_gatt_attr_read_cep, NULL, (void *)_value)
1235 :
1236 : /** @brief Read Characteristic User Description Descriptor Attribute helper
1237 : *
1238 : * Read CUD attribute value from local database storing the result into buffer
1239 : * after encoding it.
1240 : *
1241 : * @note Only use this with attributes which user_data is a NULL-terminated C
1242 : * string.
1243 : *
1244 : * @param conn Connection object
1245 : * @param attr Attribute to read
1246 : * @param buf Buffer to store the value read
1247 : * @param len Buffer length
1248 : * @param offset Start offset
1249 : *
1250 : * @return number of bytes read in case of success or negative values in
1251 : * case of error.
1252 : */
1253 1 : ssize_t bt_gatt_attr_read_cud(struct bt_conn *conn,
1254 : const struct bt_gatt_attr *attr, void *buf,
1255 : uint16_t len, uint16_t offset);
1256 :
1257 : /**
1258 : * @brief Characteristic User Format Descriptor Declaration Macro.
1259 : *
1260 : * Helper macro to declare a CUD attribute.
1261 : *
1262 : * @param _value User description NULL-terminated C string.
1263 : * @param _perm Descriptor attribute access permissions,
1264 : * a bitmap of @ref bt_gatt_perm values.
1265 : */
1266 1 : #define BT_GATT_CUD(_value, _perm) \
1267 : BT_GATT_DESCRIPTOR(BT_UUID_GATT_CUD, _perm, bt_gatt_attr_read_cud, \
1268 : NULL, (void *)_value)
1269 :
1270 : /** @brief Read Characteristic Presentation format Descriptor Attribute helper
1271 : *
1272 : * Read CPF attribute value from local database storing the result into buffer
1273 : * after encoding it.
1274 : *
1275 : * @note Only use this with attributes which user_data is a @ref bt_gatt_cpf.
1276 : *
1277 : * @param conn Connection object
1278 : * @param attr Attribute to read
1279 : * @param buf Buffer to store the value read
1280 : * @param len Buffer length
1281 : * @param offset Start offset
1282 : *
1283 : * @return number of bytes read in case of success or negative values in
1284 : * case of error.
1285 : */
1286 1 : ssize_t bt_gatt_attr_read_cpf(struct bt_conn *conn,
1287 : const struct bt_gatt_attr *attr, void *buf,
1288 : uint16_t len, uint16_t offset);
1289 :
1290 : /**
1291 : * @brief Characteristic Presentation Format Descriptor Declaration Macro.
1292 : *
1293 : * Helper macro to declare a CPF attribute.
1294 : *
1295 : * @param _value Pointer to a struct bt_gatt_cpf.
1296 : */
1297 1 : #define BT_GATT_CPF(_value) \
1298 : BT_GATT_DESCRIPTOR(BT_UUID_GATT_CPF, BT_GATT_PERM_READ, \
1299 : bt_gatt_attr_read_cpf, NULL, (void *)_value)
1300 :
1301 : /**
1302 : * @brief Descriptor Declaration Macro.
1303 : *
1304 : * Helper macro to declare a descriptor attribute.
1305 : *
1306 : * @param _uuid Descriptor attribute uuid.
1307 : * @param _perm Descriptor attribute access permissions,
1308 : * a bitmap of @ref bt_gatt_perm values.
1309 : * @param _read Descriptor attribute read callback
1310 : * (@ref bt_gatt_attr_read_func_t).
1311 : * @param _write Descriptor attribute write callback
1312 : * (@ref bt_gatt_attr_write_func_t).
1313 : * @param _user_data Descriptor attribute user data.
1314 : */
1315 1 : #define BT_GATT_DESCRIPTOR(_uuid, _perm, _read, _write, _user_data) \
1316 : BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _user_data)
1317 :
1318 : /**
1319 : * @brief Attribute Declaration Macro.
1320 : *
1321 : * Helper macro to declare an attribute.
1322 : *
1323 : * @param _uuid Attribute uuid.
1324 : * @param _perm Attribute access permissions,
1325 : * a bitmap of @ref bt_gatt_perm values.
1326 : * @param _read Attribute read callback (@ref bt_gatt_attr_read_func_t).
1327 : * @param _write Attribute write callback (@ref bt_gatt_attr_write_func_t).
1328 : * @param _user_data Attribute user data.
1329 : */
1330 1 : #define BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _user_data) \
1331 : { \
1332 : .uuid = _uuid, \
1333 : .read = _read, \
1334 : .write = _write, \
1335 : .user_data = _user_data, \
1336 : .handle = 0, \
1337 : .perm = _perm, \
1338 : }
1339 :
1340 : /** @brief Notification complete result callback.
1341 : *
1342 : * @param conn Connection object.
1343 : * @param user_data Data passed in by the user.
1344 : */
1345 1 : typedef void (*bt_gatt_complete_func_t) (struct bt_conn *conn, void *user_data);
1346 :
1347 : /** @brief GATT notification parameters
1348 : *
1349 : * See also @ref bt_gatt_notify_cb and @ref bt_gatt_notify_multiple, using this parameter.
1350 : */
1351 1 : struct bt_gatt_notify_params {
1352 : /** @brief Notification Attribute UUID type
1353 : *
1354 : * Optional, use to search for an attribute with matching UUID when
1355 : * the attribute object pointer is not known.
1356 : */
1357 1 : const struct bt_uuid *uuid;
1358 : /** @brief Notification Attribute object
1359 : *
1360 : * Optional if uuid is provided, in this case it will be used as start
1361 : * range to search for the attribute with the given UUID.
1362 : */
1363 1 : const struct bt_gatt_attr *attr;
1364 : /** Notification Value data */
1365 1 : const void *data;
1366 : /** Notification Value length */
1367 1 : uint16_t len;
1368 : /** Notification Value callback */
1369 1 : bt_gatt_complete_func_t func;
1370 : /** Notification Value callback user data */
1371 1 : void *user_data;
1372 : #if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
1373 : /** Att channel options. */
1374 1 : enum bt_att_chan_opt chan_opt;
1375 : #endif /* CONFIG_BT_EATT */
1376 : };
1377 :
1378 : /** @brief Notify attribute value change.
1379 : *
1380 : * This function works in the same way as @ref bt_gatt_notify.
1381 : * With the addition that after sending the notification the
1382 : * callback function will be called.
1383 : *
1384 : * The callback is run from System Workqueue context.
1385 : * When called from the System Workqueue context this API will not wait for
1386 : * resources for the callback but instead return an error.
1387 : *
1388 : * Alternatively it is possible to notify by UUID by setting it on the
1389 : * parameters, when using this method the attribute if provided is used as the
1390 : * start range when looking up for possible matches.
1391 : *
1392 : * @param conn Connection object.
1393 : * @param params Notification parameters.
1394 : *
1395 : * @return 0 in case of success or negative value in case of error.
1396 : */
1397 1 : int bt_gatt_notify_cb(struct bt_conn *conn,
1398 : struct bt_gatt_notify_params *params);
1399 :
1400 : /** @brief Send multiple notifications in a single PDU.
1401 : *
1402 : * The GATT Server will send a single ATT_MULTIPLE_HANDLE_VALUE_NTF PDU
1403 : * containing all the notifications passed to this API.
1404 : *
1405 : * All `params` must have the same `func` and `user_data` (due to
1406 : * implementation limitation). But `func(user_data)` will be invoked for each
1407 : * parameter.
1408 : *
1409 : * As this API may block to wait for Bluetooth Host resources, it is not
1410 : * recommended to call it from a cooperative thread or a Bluetooth callback.
1411 : *
1412 : * The peer's GATT Client must write to this device's Client Supported Features
1413 : * attribute and set the bit for Multiple Handle Value Notifications before
1414 : * this API can be used.
1415 : *
1416 : * Only use this API to force the use of the ATT_MULTIPLE_HANDLE_VALUE_NTF PDU.
1417 : * For standard applications, `bt_gatt_notify_cb` is preferred, as it will use
1418 : * this PDU if supported and automatically fallback to ATT_HANDLE_VALUE_NTF
1419 : * when not supported by the peer.
1420 : *
1421 : * This API has an additional limitation: it only accepts valid attribute
1422 : * references and not UUIDs like `bt_gatt_notify` and `bt_gatt_notify_cb`.
1423 : *
1424 : * @param conn
1425 : * Target client.
1426 : * Notifying all connected clients by passing `NULL` is not yet supported,
1427 : * please use `bt_gatt_notify` instead.
1428 : * @param num_params
1429 : * Element count of `params` array. Has to be greater than 1.
1430 : * @param params
1431 : * Array of notification parameters. It is okay to free this after calling
1432 : * this function.
1433 : *
1434 : * @retval 0
1435 : * Success. The PDU is queued for sending.
1436 : * @retval -EINVAL
1437 : * - One of the attribute handles is invalid.
1438 : * - Only one parameter was passed. This API expects 2 or more.
1439 : * - Not all `func` were equal or not all `user_data` were equal.
1440 : * - One of the characteristics is not notifiable.
1441 : * - An UUID was passed in one of the parameters.
1442 : * @retval -ERANGE
1443 : * - The notifications cannot all fit in a single ATT_MULTIPLE_HANDLE_VALUE_NTF.
1444 : * - They exceed the MTU of all open ATT bearers.
1445 : * @retval -EPERM
1446 : * The connection has a lower security level than required by one of the
1447 : * attributes.
1448 : * @retval -EOPNOTSUPP
1449 : * The peer hasn't yet communicated that it supports this PDU type.
1450 : */
1451 1 : int bt_gatt_notify_multiple(struct bt_conn *conn,
1452 : uint16_t num_params,
1453 : struct bt_gatt_notify_params params[]);
1454 :
1455 : /** @brief Notify attribute value change.
1456 : *
1457 : * Send notification of attribute value change, if connection is NULL notify
1458 : * all peer that have notification enabled via CCC otherwise do a direct
1459 : * notification only the given connection.
1460 : *
1461 : * The attribute object on the parameters can be the so called Characteristic
1462 : * Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed
1463 : * by BT_GATT_CCC, or the Characteristic Value Declaration which is
1464 : * automatically created after the Characteristic Declaration when using
1465 : * BT_GATT_CHARACTERISTIC.
1466 : *
1467 : * @param conn Connection object.
1468 : * @param attr Characteristic or Characteristic Value attribute.
1469 : * @param data Pointer to Attribute data.
1470 : * @param len Attribute value length.
1471 : *
1472 : * @return 0 in case of success or negative value in case of error.
1473 : */
1474 1 : static inline int bt_gatt_notify(struct bt_conn *conn,
1475 : const struct bt_gatt_attr *attr,
1476 : const void *data, uint16_t len)
1477 : {
1478 : struct bt_gatt_notify_params params;
1479 :
1480 : memset(¶ms, 0, sizeof(params));
1481 :
1482 : params.attr = attr;
1483 : params.data = data;
1484 : params.len = len;
1485 : #if defined(CONFIG_BT_EATT)
1486 : params.chan_opt = BT_ATT_CHAN_OPT_NONE;
1487 : #endif /* CONFIG_BT_EATT */
1488 :
1489 : return bt_gatt_notify_cb(conn, ¶ms);
1490 : }
1491 :
1492 : /** @brief Notify attribute value change by UUID.
1493 : *
1494 : * Send notification of attribute value change, if connection is NULL notify
1495 : * all peer that have notification enabled via CCC otherwise do a direct
1496 : * notification only on the given connection.
1497 : *
1498 : * The attribute object is the starting point for the search of the UUID.
1499 : *
1500 : * @param conn Connection object.
1501 : * @param uuid The UUID. If the server contains multiple services with the same
1502 : * UUID, then the first occurrence, starting from the attr given,
1503 : * is used.
1504 : * @param attr Pointer to an attribute that serves as the starting point for
1505 : * the search of a match for the UUID.
1506 : * @param data Pointer to Attribute data.
1507 : * @param len Attribute value length.
1508 : *
1509 : * @return 0 in case of success or negative value in case of error.
1510 : */
1511 1 : static inline int bt_gatt_notify_uuid(struct bt_conn *conn,
1512 : const struct bt_uuid *uuid,
1513 : const struct bt_gatt_attr *attr,
1514 : const void *data, uint16_t len)
1515 : {
1516 : struct bt_gatt_notify_params params;
1517 :
1518 : memset(¶ms, 0, sizeof(params));
1519 :
1520 : params.uuid = uuid;
1521 : params.attr = attr;
1522 : params.data = data;
1523 : params.len = len;
1524 : #if defined(CONFIG_BT_EATT)
1525 : params.chan_opt = BT_ATT_CHAN_OPT_NONE;
1526 : #endif /* CONFIG_BT_EATT */
1527 :
1528 : return bt_gatt_notify_cb(conn, ¶ms);
1529 : }
1530 :
1531 : /* Forward declaration of the bt_gatt_indicate_params structure */
1532 : struct bt_gatt_indicate_params;
1533 :
1534 : /** @typedef bt_gatt_indicate_func_t
1535 : * @brief Indication complete result callback.
1536 : *
1537 : * @param conn Connection object.
1538 : * @param params Indication params object.
1539 : * @param err ATT error code
1540 : */
1541 1 : typedef void (*bt_gatt_indicate_func_t)(struct bt_conn *conn,
1542 : struct bt_gatt_indicate_params *params,
1543 : uint8_t err);
1544 :
1545 : /** @typedef bt_gatt_indicate_params_destroy_t
1546 : * @brief Callback to destroy or clean up the GATT Indicate Value parameters.
1547 : *
1548 : * This callback function is invoked to clean up any resources associated with the
1549 : * `bt_gatt_indicate_params` structure once the GATT indication operation is completed.
1550 : *
1551 : * @param params Pointer to the GATT Indicate parameters structure to be cleaned up.
1552 : */
1553 1 : typedef void (*bt_gatt_indicate_params_destroy_t)(
1554 : struct bt_gatt_indicate_params *params);
1555 :
1556 : /** @brief GATT Indicate Value parameters
1557 : *
1558 : * See also @ref bt_gatt_indicate, using this parameter.
1559 : *
1560 : */
1561 1 : struct bt_gatt_indicate_params {
1562 : /** @brief Indicate Attribute UUID type
1563 : *
1564 : * Optional, use to search for an attribute with matching UUID when
1565 : * the attribute object pointer is not known.
1566 : */
1567 1 : const struct bt_uuid *uuid;
1568 : /** @brief Indicate Attribute object
1569 : *
1570 : * Optional if uuid is provided, in this case it will be used as start
1571 : * range to search for the attribute with the given UUID.
1572 : */
1573 1 : const struct bt_gatt_attr *attr;
1574 : /** Indicate Value callback */
1575 1 : bt_gatt_indicate_func_t func;
1576 : /** Indicate operation complete callback */
1577 1 : bt_gatt_indicate_params_destroy_t destroy;
1578 : /** Indicate Value data*/
1579 1 : const void *data;
1580 : /** Indicate Value length*/
1581 1 : uint16_t len;
1582 : /** Private reference counter */
1583 : uint8_t _ref;
1584 : #if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
1585 : /** Att channel options. */
1586 1 : enum bt_att_chan_opt chan_opt;
1587 : #endif /* CONFIG_BT_EATT */
1588 : };
1589 :
1590 : /** @brief Indicate attribute value change.
1591 : *
1592 : * Send an indication of attribute value change. if connection is NULL
1593 : * indicate all peer that have notification enabled via CCC otherwise do a
1594 : * direct indication only the given connection.
1595 : *
1596 : * The attribute object on the parameters can be the so called Characteristic
1597 : * Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed
1598 : * by BT_GATT_CCC, or the Characteristic Value Declaration which is
1599 : * automatically created after the Characteristic Declaration when using
1600 : * BT_GATT_CHARACTERISTIC.
1601 : *
1602 : * Alternatively it is possible to indicate by UUID by setting it on the
1603 : * parameters, when using this method the attribute if provided is used as the
1604 : * start range when looking up for possible matches.
1605 : *
1606 : * @note This procedure is asynchronous therefore the parameters need to
1607 : * remains valid while it is active. The procedure is active until
1608 : * the destroy callback is run.
1609 : *
1610 : * @param conn Connection object.
1611 : * @param params Indicate parameters.
1612 : *
1613 : * @return 0 in case of success or negative value in case of error.
1614 : */
1615 1 : int bt_gatt_indicate(struct bt_conn *conn,
1616 : struct bt_gatt_indicate_params *params);
1617 :
1618 : /** @brief Check if connection have subscribed to attribute
1619 : *
1620 : * Check if the connection has subscribed to an attribute value change.
1621 : *
1622 : * The attribute object can be the so called Characteristic Declaration,
1623 : * which is usually declared with BT_GATT_CHARACTERISTIC followed
1624 : * by BT_GATT_CCC, or the Characteristic Value Declaration which is
1625 : * automatically created after the Characteristic Declaration when using
1626 : * BT_GATT_CHARACTERISTIC, or the Client Characteristic Configuration
1627 : * Descriptor (CCCD) which is created by BT_GATT_CCC.
1628 : *
1629 : * @param conn Connection object.
1630 : * @param attr Attribute object.
1631 : * @param ccc_type The subscription type, @ref BT_GATT_CCC_NOTIFY and/or
1632 : * @ref BT_GATT_CCC_INDICATE.
1633 : *
1634 : * @return true if the attribute object has been subscribed.
1635 : */
1636 1 : bool bt_gatt_is_subscribed(struct bt_conn *conn,
1637 : const struct bt_gatt_attr *attr, uint16_t ccc_type);
1638 :
1639 : /** @brief Get ATT MTU for a connection
1640 : *
1641 : * Get negotiated ATT connection MTU, note that this does not equal the largest
1642 : * amount of attribute data that can be transferred within a single packet.
1643 : *
1644 : * @param conn Connection object.
1645 : *
1646 : * @return MTU in bytes
1647 : */
1648 1 : uint16_t bt_gatt_get_mtu(struct bt_conn *conn);
1649 :
1650 : /** @brief Get Unenhanced ATT (UATT) MTU for a connection
1651 : *
1652 : * Get UATT connection MTU.
1653 : *
1654 : * The ATT_MTU defines the largest size of an ATT PDU, encompassing the ATT
1655 : * opcode, additional fields, and any attribute value payload. Consequently,
1656 : * the maximum size of a value payload is less and varies based on the type
1657 : * of ATT PDU. For example, in an ATT_HANDLE_VALUE_NTF PDU, the Attribute Value
1658 : * field can contain up to ATT_MTU - 3 octets (size of opcode and handle).
1659 : *
1660 : * @param conn Connection object.
1661 : *
1662 : * @return 0 if @p conn does not have an UATT ATT_MTU (e.g: disconnected).
1663 : * @return Current UATT ATT_MTU.
1664 : */
1665 1 : uint16_t bt_gatt_get_uatt_mtu(struct bt_conn *conn);
1666 :
1667 : /** @} */
1668 :
1669 : /**
1670 : * @defgroup bt_gatt_client GATT Client APIs
1671 : * @ingroup bt_gatt
1672 : * @{
1673 : */
1674 :
1675 : /** @brief GATT Exchange MTU parameters
1676 : *
1677 : * Used with @ref bt_gatt_exchange_mtu function to initiate an MTU exchange. The
1678 : * response is handled in the callback @p func, which is called upon
1679 : * completion from the 'config BT_RECV_CONTEXT' context.
1680 : *
1681 : * @p params must remain valid until the callback executes.
1682 : */
1683 1 : struct bt_gatt_exchange_params {
1684 : /** Callback for MTU exchange response */
1685 1 : void (*func)(struct bt_conn *conn, uint8_t err,
1686 : struct bt_gatt_exchange_params *params);
1687 : };
1688 :
1689 : /** @brief Exchange MTU
1690 : *
1691 : * Once per connection, this client procedure can be used to set the MTU to
1692 : * the maximum possible size the buffers can hold.
1693 : *
1694 : * As the response comes in callback @p params->func, for example
1695 : * @ref bt_gatt_get_mtu can be invoked in the mtu_exchange-callback to read
1696 : * out the new negotiated ATT connection MTU. The callback is run from the
1697 : * context specified by 'config BT_RECV_CONTEXT' and @p params must remain
1698 : * valid until start of callback.
1699 : *
1700 : * @param conn Connection object.
1701 : * @param params Exchange MTU parameters.
1702 : *
1703 : * @retval 0 Successfully queued request. Will call @p params->func on
1704 : * resolution.
1705 : *
1706 : * @retval -ENOMEM ATT request queue is full and blocking would cause deadlock.
1707 : * Allow a pending request to resolve before retrying, or call this function
1708 : * from a separate thread to get blocking behavior. Queue size is controlled
1709 : * by @kconfig{CONFIG_BT_ATT_TX_COUNT}.
1710 : *
1711 : * @retval -EALREADY The MTU exchange procedure has been already performed.
1712 : */
1713 1 : int bt_gatt_exchange_mtu(struct bt_conn *conn,
1714 : struct bt_gatt_exchange_params *params);
1715 :
1716 : struct bt_gatt_discover_params;
1717 :
1718 : /** @typedef bt_gatt_discover_func_t
1719 : * @brief Discover attribute callback function.
1720 : *
1721 : * @param conn Connection object.
1722 : * @param attr Attribute found, or NULL if not found.
1723 : * @param params Discovery parameters given.
1724 : *
1725 : * If discovery procedure has completed this callback will be called with
1726 : * attr set to NULL. This will not happen if procedure was stopped by returning
1727 : * BT_GATT_ITER_STOP.
1728 : *
1729 : * The attribute object as well as its UUID and value objects are temporary and
1730 : * must be copied to in order to cache its information.
1731 : *
1732 : * @note @ref bt_gatt_attr is given as an argument to @ref bt_gatt_discover function, but
1733 : * it's not a proper object of this type. @ref bt_gatt_attr.perm, and methods
1734 : * bt_gatt_attr.read() and bt_gatt_attr.write() are not available, and it's
1735 : * unsound to pass the pointer to GATT server APIs.
1736 : * Only the following fields of the attribute contains valid information:
1737 : * - uuid UUID representing the type of attribute.
1738 : * - handle Handle in the remote database.
1739 : * - user_data The value of the attribute, if the discovery type maps to an
1740 : * ATT operation that provides this information. NULL otherwise.
1741 : * See below.
1742 : *
1743 : * The effective type of @c attr->user_data is determined by @c params. Note
1744 : * that the fields @c params->type and @c params->uuid are left unchanged by
1745 : * the discovery procedure.
1746 : *
1747 : * @c params->type | @c params->uuid | Type of @c attr->user_data
1748 : * -------------------------------------|-------------------------|---------------------------
1749 : * @ref BT_GATT_DISCOVER_PRIMARY | any | @ref bt_gatt_service_val
1750 : * @ref BT_GATT_DISCOVER_SECONDARY | any | @ref bt_gatt_service_val
1751 : * @ref BT_GATT_DISCOVER_INCLUDE | any | @ref bt_gatt_include
1752 : * @ref BT_GATT_DISCOVER_CHARACTERISTIC | any | @ref bt_gatt_chrc
1753 : * @ref BT_GATT_DISCOVER_STD_CHAR_DESC | @ref BT_UUID_GATT_CEP | @ref bt_gatt_cep
1754 : * @ref BT_GATT_DISCOVER_STD_CHAR_DESC | @ref BT_UUID_GATT_CCC | @ref bt_gatt_ccc
1755 : * @ref BT_GATT_DISCOVER_STD_CHAR_DESC | @ref BT_UUID_GATT_SCC | @ref bt_gatt_scc
1756 : * @ref BT_GATT_DISCOVER_STD_CHAR_DESC | @ref BT_UUID_GATT_CPF | @ref bt_gatt_cpf
1757 : * @ref BT_GATT_DISCOVER_DESCRIPTOR | any | NULL
1758 : * @ref BT_GATT_DISCOVER_ATTRIBUTE | any | NULL
1759 : *
1760 : * Also consider if using read-by-type instead of discovery is more convenient.
1761 : * See @ref bt_gatt_read with @ref bt_gatt_read_params.handle_count set to
1762 : * @c 0.
1763 : *
1764 : * @return BT_GATT_ITER_CONTINUE to continue discovery procedure.
1765 : * @return BT_GATT_ITER_STOP to stop discovery procedure.
1766 : */
1767 1 : typedef uint8_t (*bt_gatt_discover_func_t)(struct bt_conn *conn,
1768 : const struct bt_gatt_attr *attr,
1769 : struct bt_gatt_discover_params *params);
1770 :
1771 : /** GATT Discover types */
1772 1 : enum bt_gatt_discover_type {
1773 : /** Discover Primary Services. */
1774 : BT_GATT_DISCOVER_PRIMARY,
1775 : /** Discover Secondary Services. */
1776 : BT_GATT_DISCOVER_SECONDARY,
1777 : /** Discover Included Services. */
1778 : BT_GATT_DISCOVER_INCLUDE,
1779 : /** @brief Discover Characteristic Values.
1780 : *
1781 : * Discover Characteristic Value and its properties.
1782 : */
1783 : BT_GATT_DISCOVER_CHARACTERISTIC,
1784 : /** @brief Discover Descriptors.
1785 : *
1786 : * Discover Attributes which are not services or characteristics.
1787 : *
1788 : * @note The use of this type of discover is not recommended for
1789 : * discovering in ranges across multiple services/characteristics
1790 : * as it may incur in extra round trips.
1791 : */
1792 : BT_GATT_DISCOVER_DESCRIPTOR,
1793 : /** @brief Discover Attributes.
1794 : *
1795 : * Discover Attributes of any type.
1796 : *
1797 : * @note The use of this type of discover is not recommended for
1798 : * discovering in ranges across multiple services/characteristics
1799 : * as it may incur in more round trips.
1800 : */
1801 : BT_GATT_DISCOVER_ATTRIBUTE,
1802 : /** @brief Discover standard characteristic descriptor values.
1803 : *
1804 : * Discover standard characteristic descriptor values and their
1805 : * properties.
1806 : * Supported descriptors:
1807 : * - Characteristic Extended Properties
1808 : * - Client Characteristic Configuration
1809 : * - Server Characteristic Configuration
1810 : * - Characteristic Presentation Format
1811 : */
1812 : BT_GATT_DISCOVER_STD_CHAR_DESC,
1813 : };
1814 :
1815 : /** Handle value to denote that the CCC will be automatically discovered */
1816 1 : #define BT_GATT_AUTO_DISCOVER_CCC_HANDLE 0x0000U
1817 :
1818 : /** @brief GATT Discover Attributes parameters */
1819 1 : struct bt_gatt_discover_params {
1820 : /** Discover UUID type */
1821 1 : const struct bt_uuid *uuid;
1822 : /** Discover attribute callback */
1823 1 : bt_gatt_discover_func_t func;
1824 : union {
1825 : /** See @ref bt_gatt_include for more on included services. */
1826 : struct {
1827 : /** Include service attribute declaration handle */
1828 1 : uint16_t attr_handle;
1829 : /** Starting attribute handle for included service */
1830 1 : uint16_t start_handle;
1831 : /** Ending attribute handle for included service */
1832 1 : uint16_t end_handle;
1833 : } _included;
1834 : /** Starting attribute handle to begin discovery */
1835 : uint16_t start_handle;
1836 0 : };
1837 : /** @brief Ending attribute handle to stop discovery at
1838 : *
1839 : * @note When discovery begins this can be set to
1840 : * @ref BT_ATT_LAST_ATTRIBUTE_HANDLE to discover all attributes
1841 : * in the service.
1842 : */
1843 : uint16_t end_handle;
1844 : /** Discover type */
1845 1 : uint8_t type;
1846 : #if defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__)
1847 : /** Only for stack-internal use, used for automatic discovery. */
1848 1 : struct bt_gatt_subscribe_params *sub_params;
1849 : #endif /* defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__) */
1850 : #if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
1851 : /** Att channel options. */
1852 1 : enum bt_att_chan_opt chan_opt;
1853 : #endif /* CONFIG_BT_EATT */
1854 : };
1855 :
1856 : /** @brief GATT Discover function
1857 : *
1858 : * This procedure is used by a client to discover attributes on a server.
1859 : *
1860 : * Primary Service Discovery: Procedure allows to discover primary services
1861 : * either by Discover All Primary Services or
1862 : * Discover Primary Services by Service UUID.
1863 : * Include Service Discovery: Procedure allows to discover all Include Services
1864 : * within specified range.
1865 : * Characteristic Discovery: Procedure allows to discover all characteristics
1866 : * within specified handle range as well as
1867 : * discover characteristics with specified UUID.
1868 : * Descriptors Discovery: Procedure allows to discover all characteristic
1869 : * descriptors within specified range.
1870 : *
1871 : * For each attribute found the callback is called which can then decide
1872 : * whether to continue discovering or stop.
1873 : *
1874 : * The Response comes in callback @p params->func. The callback is run from
1875 : * the BT RX thread. @p params must remain valid until start of callback where
1876 : * iter `attr` is `NULL` or callback will return `BT_GATT_ITER_STOP`.
1877 : *
1878 : * @param conn Connection object.
1879 : * @param params Discover parameters.
1880 : *
1881 : * @retval 0 Successfully queued request. Will call @p params->func on
1882 : * resolution.
1883 : *
1884 : * @retval -ENOMEM ATT request queue is full and blocking would cause deadlock.
1885 : * Allow a pending request to resolve before retrying, or call this function
1886 : * from a separate thread to get blocking behavior. Queue size is controlled
1887 : * by @kconfig{CONFIG_BT_ATT_TX_COUNT}.
1888 : */
1889 1 : int bt_gatt_discover(struct bt_conn *conn,
1890 : struct bt_gatt_discover_params *params);
1891 :
1892 : struct bt_gatt_read_params;
1893 :
1894 : /** @typedef bt_gatt_read_func_t
1895 : * @brief Read callback function
1896 : *
1897 : * When reading using by_uuid, `params->start_handle` is the attribute handle
1898 : * for this `data` item.
1899 : *
1900 : * If the received data length is invalid, the callback will called with the
1901 : * error @ref BT_ATT_ERR_INVALID_PDU.
1902 : *
1903 : * @param conn Connection object.
1904 : * @param err ATT error code.
1905 : * @param params Read parameters used.
1906 : * @param data Attribute value data. NULL means read has completed.
1907 : * @param length Attribute value length.
1908 : *
1909 : * @return BT_GATT_ITER_CONTINUE if should continue to the next attribute.
1910 : * @return BT_GATT_ITER_STOP to stop.
1911 : */
1912 1 : typedef uint8_t (*bt_gatt_read_func_t)(struct bt_conn *conn, uint8_t err,
1913 : struct bt_gatt_read_params *params,
1914 : const void *data, uint16_t length);
1915 :
1916 : /** @brief GATT Read parameters */
1917 1 : struct bt_gatt_read_params {
1918 : /** Read attribute callback. */
1919 1 : bt_gatt_read_func_t func;
1920 : /** If equals to 1 single.handle and single.offset are used.
1921 : * If greater than 1 multiple.handles are used.
1922 : * If equals to 0 by_uuid is used for Read Using Characteristic UUID.
1923 : */
1924 1 : size_t handle_count;
1925 : union {
1926 : struct {
1927 : /** Attribute handle. */
1928 1 : uint16_t handle;
1929 : /** Attribute data offset. */
1930 1 : uint16_t offset;
1931 0 : } single;
1932 : struct {
1933 : /** Attribute handles to read with Read Multiple
1934 : * Characteristic Values.
1935 : */
1936 1 : uint16_t *handles;
1937 : /** If true use Read Multiple Variable Length
1938 : * Characteristic Values procedure.
1939 : * The values of the set of attributes may be of
1940 : * variable or unknown length.
1941 : * If false use Read Multiple Characteristic Values
1942 : * procedure.
1943 : * The values of the set of attributes must be of a
1944 : * known fixed length, with the exception of the last
1945 : * value that can have a variable length.
1946 : */
1947 1 : bool variable;
1948 0 : } multiple;
1949 : struct {
1950 : /** @brief Requested start attribute handle number.
1951 : *
1952 : * @details The starting handle is set to the starting point of the range
1953 : * over which this read should be performed. For example, this could be
1954 : * set to @ref BT_ATT_FIRST_ATTRIBUTE_HANDLE to set the starting point of
1955 : * the range at the beginning of the GATT database, or to the starting
1956 : * handle of a service after discovery.
1957 : *
1958 : * This value is automatically incremented by the stack after
1959 : * processing each matching handle-value pair returned by the server.
1960 : */
1961 1 : uint16_t start_handle;
1962 : /** @brief Requested end attribute handle number.
1963 : *
1964 : * @details The end handle is set to the ending point of the range over
1965 : * which this read should be performed. For example, this could be set to
1966 : * @ref BT_ATT_LAST_ATTRIBUTE_HANDLE to set the ending point of the range
1967 : * at the end of the GATT database, or to the end handle for service after
1968 : * discovery, where the end_handle is available in the
1969 : * @ref bt_gatt_service_val.
1970 : */
1971 1 : uint16_t end_handle;
1972 : /** 2 or 16 octet UUID. */
1973 1 : const struct bt_uuid *uuid;
1974 0 : } by_uuid;
1975 0 : };
1976 : #if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
1977 : /** Att channel options. */
1978 1 : enum bt_att_chan_opt chan_opt;
1979 : #endif /* CONFIG_BT_EATT */
1980 : /** Internal */
1981 : uint16_t _att_mtu;
1982 : };
1983 :
1984 : /** @brief Read Attribute Value by handle
1985 : *
1986 : * This procedure reads the attribute value and returns it to the callback.
1987 : *
1988 : * When reading attributes by UUID the callback can be called multiple times
1989 : * depending on how many instances of a given UUID exists with the start_handle
1990 : * being updated for each instance.
1991 : *
1992 : * To perform a GATT Long Read procedure, start with a Characteristic Value
1993 : * Read (by setting @c offset @c 0 and @c handle_count @c 1) and then return
1994 : * @ref BT_GATT_ITER_CONTINUE from the callback. This is equivalent to calling
1995 : * @ref bt_gatt_read again, but with the correct offset to continue the read.
1996 : * This may be repeated until the procedure is complete, which is signaled by
1997 : * the callback being called with @p data set to @c NULL.
1998 : *
1999 : * Note that returning @ref BT_GATT_ITER_CONTINUE is really starting a new ATT
2000 : * operation, so this can fail to allocate resources. However, all API errors
2001 : * are reported as if the server returned @ref BT_ATT_ERR_UNLIKELY. There is no
2002 : * way to distinguish between this condition and a @ref BT_ATT_ERR_UNLIKELY
2003 : * response from the server itself.
2004 : *
2005 : * Note that the effect of returning @ref BT_GATT_ITER_CONTINUE from the
2006 : * callback varies depending on the type of read operation.
2007 : *
2008 : * The Response comes in callback @p params->func. The callback is run from
2009 : * the context specified by 'config BT_RECV_CONTEXT'.
2010 : * @p params must remain valid until start of callback.
2011 : * If the received data length is invalid, the callback @p params->func will
2012 : * called with the error @ref BT_ATT_ERR_INVALID_PDU.
2013 : *
2014 : * @param conn Connection object.
2015 : * @param params Read parameters.
2016 : *
2017 : * @retval 0 Successfully queued request. Will call @p params->func on
2018 : * resolution.
2019 : *
2020 : * @retval -ENOMEM ATT request queue is full and blocking would cause deadlock.
2021 : * Allow a pending request to resolve before retrying, or call this function
2022 : * from a separate thread to get blocking behavior. Queue size is controlled
2023 : * by @kconfig{CONFIG_BT_ATT_TX_COUNT}.
2024 : */
2025 1 : int bt_gatt_read(struct bt_conn *conn, struct bt_gatt_read_params *params);
2026 :
2027 : struct bt_gatt_write_params;
2028 :
2029 : /** @typedef bt_gatt_write_func_t
2030 : * @brief Write callback function
2031 : *
2032 : * @param conn Connection object.
2033 : * @param err ATT error code.
2034 : * @param params Write parameters used.
2035 : */
2036 1 : typedef void (*bt_gatt_write_func_t)(struct bt_conn *conn, uint8_t err,
2037 : struct bt_gatt_write_params *params);
2038 :
2039 : /** @brief GATT Write parameters */
2040 1 : struct bt_gatt_write_params {
2041 : /** Response callback */
2042 1 : bt_gatt_write_func_t func;
2043 : /** Attribute handle */
2044 1 : uint16_t handle;
2045 : /** Attribute data offset */
2046 1 : uint16_t offset;
2047 : /** Data to be written */
2048 1 : const void *data;
2049 : /** Length of the data */
2050 1 : uint16_t length;
2051 : #if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
2052 : /** Att channel options. */
2053 1 : enum bt_att_chan_opt chan_opt;
2054 : #endif /* CONFIG_BT_EATT */
2055 : };
2056 :
2057 : /** @brief Write Attribute Value by handle
2058 : *
2059 : * The Response comes in callback @p params->func. The callback is run from
2060 : * the context specified by 'config BT_RECV_CONTEXT'.
2061 : * @p params must remain valid until start of callback.
2062 : *
2063 : * @param conn Connection object.
2064 : * @param params Write parameters.
2065 : *
2066 : * @retval 0 Successfully queued request. Will call @p params->func on
2067 : * resolution.
2068 : *
2069 : * @retval -ENOMEM ATT request queue is full and blocking would cause deadlock.
2070 : * Allow a pending request to resolve before retrying, or call this function
2071 : * from a separate thread to get blocking behavior. Queue size is controlled
2072 : * by @kconfig{CONFIG_BT_ATT_TX_COUNT}.
2073 : */
2074 1 : int bt_gatt_write(struct bt_conn *conn, struct bt_gatt_write_params *params);
2075 :
2076 : /** @brief Write Attribute Value by handle without response with callback.
2077 : *
2078 : * This function works in the same way as @ref bt_gatt_write_without_response.
2079 : * With the addition that after sending the write the callback function will be
2080 : * called.
2081 : *
2082 : * The callback is run from System Workqueue context.
2083 : * When called from the System Workqueue context this API will not wait for
2084 : * resources for the callback but instead return an error.
2085 : *
2086 : * @param conn Connection object.
2087 : * @param handle Attribute handle.
2088 : * @param data Data to be written.
2089 : * @param length Data length.
2090 : * @param sign Whether to sign data.
2091 : * @param func Transmission complete callback.
2092 : * @param user_data User data to be passed back to callback.
2093 : *
2094 : * @retval 0 Successfully queued request.
2095 : *
2096 : * @retval -ENOMEM ATT request queue is full and blocking would cause deadlock.
2097 : * Allow a pending request to resolve before retrying, or call this function
2098 : * from a separate thread to get blocking behavior. Queue size is controlled
2099 : * by @kconfig{CONFIG_BT_ATT_TX_COUNT}.
2100 : */
2101 1 : int bt_gatt_write_without_response_cb(struct bt_conn *conn, uint16_t handle,
2102 : const void *data, uint16_t length,
2103 : bool sign, bt_gatt_complete_func_t func,
2104 : void *user_data);
2105 :
2106 : /** @brief Write Attribute Value by handle without response
2107 : *
2108 : * This procedure write the attribute value without requiring an
2109 : * acknowledgment that the write was successfully performed
2110 : *
2111 : * @param conn Connection object.
2112 : * @param handle Attribute handle.
2113 : * @param data Data to be written.
2114 : * @param length Data length.
2115 : * @param sign Whether to sign data.
2116 : *
2117 : * @retval 0 Successfully queued request.
2118 : *
2119 : * @retval -ENOMEM ATT request queue is full and blocking would cause deadlock.
2120 : * Allow a pending request to resolve before retrying, or call this function
2121 : * from a separate thread to get blocking behavior. Queue size is controlled
2122 : * by @kconfig{CONFIG_BT_ATT_TX_COUNT}.
2123 : */
2124 1 : static inline int bt_gatt_write_without_response(struct bt_conn *conn,
2125 : uint16_t handle, const void *data,
2126 : uint16_t length, bool sign)
2127 : {
2128 : return bt_gatt_write_without_response_cb(conn, handle, data, length,
2129 : sign, NULL, NULL);
2130 : }
2131 :
2132 : struct bt_gatt_subscribe_params;
2133 :
2134 : /** @typedef bt_gatt_notify_func_t
2135 : * @brief Notification callback function
2136 : *
2137 : * In the case of an empty notification, the @p data pointer will be non-NULL
2138 : * while the @p length will be 0, which is due to the special case where
2139 : * a @p data NULL pointer means unsubscribed.
2140 : *
2141 : * @param conn Connection object. May be NULL, indicating that the peer is
2142 : * being unpaired
2143 : * @param params Subscription parameters.
2144 : * @param data Attribute value data. If NULL then subscription was removed.
2145 : * @param length Attribute value length.
2146 : *
2147 : * @return BT_GATT_ITER_CONTINUE to continue receiving value notifications.
2148 : * BT_GATT_ITER_STOP to unsubscribe from value notifications.
2149 : */
2150 1 : typedef uint8_t (*bt_gatt_notify_func_t)(struct bt_conn *conn,
2151 : struct bt_gatt_subscribe_params *params,
2152 : const void *data, uint16_t length);
2153 :
2154 : /** @typedef bt_gatt_subscribe_func_t
2155 : * @brief Subscription callback function
2156 : *
2157 : * @param conn Connection object.
2158 : * @param err ATT error code.
2159 : * @param params Subscription parameters used.
2160 : */
2161 1 : typedef void (*bt_gatt_subscribe_func_t)(struct bt_conn *conn, uint8_t err,
2162 : struct bt_gatt_subscribe_params *params);
2163 :
2164 : /** Subscription flags */
2165 0 : enum bt_gatt_sub_flag {
2166 : /** @brief Persistence flag
2167 : *
2168 : * If set, indicates that the subscription is not saved
2169 : * on the GATT server side. Therefore, upon disconnection,
2170 : * the subscription will be automatically removed
2171 : * from the client's subscriptions list and
2172 : * when the client reconnects, it will have to
2173 : * issue a new subscription.
2174 : */
2175 : BT_GATT_SUBSCRIBE_FLAG_VOLATILE,
2176 :
2177 : /** @brief No resubscribe flag
2178 : *
2179 : * By default when BT_GATT_SUBSCRIBE_FLAG_VOLATILE is unset, the
2180 : * subscription will be automatically renewed when the client
2181 : * reconnects, as a workaround for GATT servers that do not persist
2182 : * subscriptions.
2183 : *
2184 : * This flag will disable the automatic resubscription. It is useful
2185 : * if the application layer knows that the GATT server remembers
2186 : * subscriptions from previous connections and wants to avoid renewing
2187 : * the subscriptions.
2188 : */
2189 : BT_GATT_SUBSCRIBE_FLAG_NO_RESUB,
2190 :
2191 : /** @brief Write pending flag
2192 : *
2193 : * If set, indicates write operation is pending waiting remote end to
2194 : * respond.
2195 : *
2196 : * @note Internal use only.
2197 : */
2198 : BT_GATT_SUBSCRIBE_FLAG_WRITE_PENDING,
2199 :
2200 : /** @brief Sent flag
2201 : *
2202 : * If set, indicates that a subscription request (CCC write) has
2203 : * already been sent in the active connection.
2204 : *
2205 : * Used to avoid sending subscription requests multiple times when the
2206 : * @kconfig{CONFIG_BT_GATT_AUTO_RESUBSCRIBE} quirk is enabled.
2207 : *
2208 : * @note Internal use only.
2209 : */
2210 : BT_GATT_SUBSCRIBE_FLAG_SENT,
2211 :
2212 : BT_GATT_SUBSCRIBE_NUM_FLAGS
2213 : };
2214 :
2215 : /** @brief GATT Subscribe parameters */
2216 1 : struct bt_gatt_subscribe_params {
2217 : /** Notification value callback */
2218 1 : bt_gatt_notify_func_t notify;
2219 : /** Subscribe CCC write request response callback
2220 : * If given, called with the subscription parameters given when subscribing
2221 : */
2222 1 : bt_gatt_subscribe_func_t subscribe;
2223 :
2224 : /** Subscribe value handle */
2225 1 : uint16_t value_handle;
2226 : /** Subscribe CCC handle */
2227 1 : uint16_t ccc_handle;
2228 : #if defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__)
2229 : /** Subscribe End handle (for automatic discovery) */
2230 1 : uint16_t end_handle;
2231 : /** Discover parameters used when ccc_handle = @ref BT_GATT_AUTO_DISCOVER_CCC_HANDLE */
2232 1 : struct bt_gatt_discover_params *disc_params;
2233 : #endif /* defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__) */
2234 : /** Subscribe value */
2235 1 : uint16_t value;
2236 : #if defined(CONFIG_BT_SMP)
2237 : /** Minimum required security for received notification. Notifications
2238 : * and indications received over a connection with a lower security
2239 : * level are silently discarded.
2240 : */
2241 1 : bt_security_t min_security;
2242 : #endif
2243 : /** Subscription flags, see @ref bt_gatt_sub_flag */
2244 1 : ATOMIC_DEFINE(flags, BT_GATT_SUBSCRIBE_NUM_FLAGS);
2245 :
2246 : /** @cond INTERNAL_HIDDEN
2247 : * Field used for list handling.
2248 : */
2249 : sys_snode_t node;
2250 : /** @endcond */
2251 : #if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
2252 : /** Att channel options. */
2253 1 : enum bt_att_chan_opt chan_opt;
2254 : #endif /* CONFIG_BT_EATT */
2255 : };
2256 :
2257 : /** @brief Subscribe Attribute Value Notification
2258 : *
2259 : * This procedure subscribe to value notification using the Client
2260 : * Characteristic Configuration handle.
2261 : * If notification received subscribe value callback is called to return
2262 : * notified value. One may then decide whether to unsubscribe directly from
2263 : * this callback. Notification callback with NULL data will not be called if
2264 : * subscription was removed by this method.
2265 : *
2266 : * The Response comes in callback @p params->subscribe. The callback is run from
2267 : * the context specified by 'config BT_RECV_CONTEXT'.
2268 : * The Notification callback @p params->notify is also called from the BT RX
2269 : * thread.
2270 : *
2271 : * @note Notifications are asynchronous therefore the @p params must remain
2272 : * valid while subscribed and cannot be reused for additional subscriptions
2273 : * whilst active.
2274 : *
2275 : * @param conn Connection object.
2276 : * @param params Subscribe parameters.
2277 : *
2278 : * @retval 0 Successfully queued request. Will call @p params->write on
2279 : * resolution.
2280 : *
2281 : * @retval -ENOMEM ATT request queue is full and blocking would cause deadlock.
2282 : * Allow a pending request to resolve before retrying, or call this function
2283 : * from a separate thread to get blocking behavior. Queue size is controlled
2284 : * by @kconfig{CONFIG_BT_ATT_TX_COUNT}.
2285 : *
2286 : * @retval -EALREADY if there already exist a subscription using the @p params.
2287 : *
2288 : * @retval -EBUSY if @p params.ccc_handle is 0 and @kconfig{CONFIG_BT_GATT_AUTO_DISCOVER_CCC} is
2289 : * enabled and discovery for the @p params is already in progress.
2290 : */
2291 1 : int bt_gatt_subscribe(struct bt_conn *conn,
2292 : struct bt_gatt_subscribe_params *params);
2293 :
2294 : /** @brief Resubscribe Attribute Value Notification subscription
2295 : *
2296 : * Resubscribe to Attribute Value Notification when already subscribed from a
2297 : * previous connection. The GATT server will remember subscription from
2298 : * previous connections when bonded, so resubscribing can be done without
2299 : * performing a new subscribe procedure after a power cycle.
2300 : *
2301 : * @note Notifications are asynchronous therefore the parameters need to
2302 : * remain valid while subscribed.
2303 : *
2304 : * @param id Local identity (in most cases BT_ID_DEFAULT).
2305 : * @param peer Remote address.
2306 : * @param params Subscribe parameters.
2307 : *
2308 : * @return 0 in case of success or negative value in case of error.
2309 : */
2310 1 : int bt_gatt_resubscribe(uint8_t id, const bt_addr_le_t *peer,
2311 : struct bt_gatt_subscribe_params *params);
2312 :
2313 : /** @brief Unsubscribe Attribute Value Notification
2314 : *
2315 : * This procedure unsubscribe to value notification using the Client
2316 : * Characteristic Configuration handle. Notification callback with NULL data
2317 : * will be called if subscription was removed by this call, until then the
2318 : * parameters cannot be reused.
2319 : *
2320 : * The Response comes in callback @p params->func. The callback is run from
2321 : * the BT RX thread.
2322 : *
2323 : * @param conn Connection object.
2324 : * @param params Subscribe parameters. The parameters shall be a @ref bt_gatt_subscribe_params from
2325 : * a previous call to bt_gatt_subscribe().
2326 : *
2327 : * @retval 0 Successfully queued request. Will call @p params->write on
2328 : * resolution.
2329 : *
2330 : * @retval -ENOMEM ATT request queue is full and blocking would cause deadlock.
2331 : * Allow a pending request to resolve before retrying, or call this function
2332 : * from a separate thread to get blocking behavior. Queue size is controlled
2333 : * by @kconfig{CONFIG_BT_ATT_TX_COUNT}.
2334 : */
2335 1 : int bt_gatt_unsubscribe(struct bt_conn *conn,
2336 : struct bt_gatt_subscribe_params *params);
2337 :
2338 : /** @brief Try to cancel the first pending request identified by @p params.
2339 : *
2340 : * This function does not release @p params for reuse. The usual callbacks
2341 : * for the request still apply. A successful cancel simulates a
2342 : * #BT_ATT_ERR_UNLIKELY response from the server.
2343 : *
2344 : * This function can cancel the following request functions:
2345 : * - #bt_gatt_exchange_mtu
2346 : * - #bt_gatt_discover
2347 : * - #bt_gatt_read
2348 : * - #bt_gatt_write
2349 : * - #bt_gatt_subscribe
2350 : * - #bt_gatt_unsubscribe
2351 : *
2352 : * @param conn The connection the request was issued on.
2353 : * @param params The address `params` used in the request function call.
2354 : */
2355 1 : void bt_gatt_cancel(struct bt_conn *conn, void *params);
2356 :
2357 : /** @} */
2358 :
2359 : #ifdef __cplusplus
2360 : }
2361 : #endif
2362 :
2363 : /**
2364 : * @}
2365 : */
2366 :
2367 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_GATT_H_ */
|
