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