1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 #ifndef H_BLE_GATT_ 21 #define H_BLE_GATT_ 22 23 /** 24 * @brief Bluetooth Generic Attribute Profile (GATT) 25 * @defgroup bt_gatt Bluetooth Generic Attribute Profile (GATT) 26 * @ingroup bt_host 27 * @{ 28 */ 29 30 #include <stdint.h> 31 #include "host/ble_att.h" 32 #include "host/ble_uuid.h" 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 struct ble_hs_conn; 38 struct ble_att_error_rsp; 39 struct ble_hs_cfg; 40 41 #define BLE_GATT_REGISTER_OP_SVC 1 42 #define BLE_GATT_REGISTER_OP_CHR 2 43 #define BLE_GATT_REGISTER_OP_DSC 3 44 45 #define BLE_GATT_SVC_UUID16 0x1801 46 #define BLE_GATT_DSC_CLT_CFG_UUID16 0x2902 47 48 #define BLE_GATT_CHR_PROP_BROADCAST 0x01 49 #define BLE_GATT_CHR_PROP_READ 0x02 50 #define BLE_GATT_CHR_PROP_WRITE_NO_RSP 0x04 51 #define BLE_GATT_CHR_PROP_WRITE 0x08 52 #define BLE_GATT_CHR_PROP_NOTIFY 0x10 53 #define BLE_GATT_CHR_PROP_INDICATE 0x20 54 #define BLE_GATT_CHR_PROP_AUTH_SIGN_WRITE 0x40 55 #define BLE_GATT_CHR_PROP_EXTENDED 0x80 56 57 #define BLE_GATT_ACCESS_OP_READ_CHR 0 58 #define BLE_GATT_ACCESS_OP_WRITE_CHR 1 59 #define BLE_GATT_ACCESS_OP_READ_DSC 2 60 #define BLE_GATT_ACCESS_OP_WRITE_DSC 3 61 62 #define BLE_GATT_CHR_F_BROADCAST 0x0001 63 #define BLE_GATT_CHR_F_READ 0x0002 64 #define BLE_GATT_CHR_F_WRITE_NO_RSP 0x0004 65 #define BLE_GATT_CHR_F_WRITE 0x0008 66 #define BLE_GATT_CHR_F_NOTIFY 0x0010 67 #define BLE_GATT_CHR_F_INDICATE 0x0020 68 #define BLE_GATT_CHR_F_AUTH_SIGN_WRITE 0x0040 69 #define BLE_GATT_CHR_F_RELIABLE_WRITE 0x0080 70 #define BLE_GATT_CHR_F_AUX_WRITE 0x0100 71 #define BLE_GATT_CHR_F_READ_ENC 0x0200 72 #define BLE_GATT_CHR_F_READ_AUTHEN 0x0400 73 #define BLE_GATT_CHR_F_READ_AUTHOR 0x0800 74 #define BLE_GATT_CHR_F_WRITE_ENC 0x1000 75 #define BLE_GATT_CHR_F_WRITE_AUTHEN 0x2000 76 #define BLE_GATT_CHR_F_WRITE_AUTHOR 0x4000 77 78 #define BLE_GATT_SVC_TYPE_END 0 79 #define BLE_GATT_SVC_TYPE_PRIMARY 1 80 #define BLE_GATT_SVC_TYPE_SECONDARY 2 81 82 /*** @client. */ 83 struct ble_gatt_error { 84 uint16_t status; 85 uint16_t att_handle; 86 }; 87 88 struct ble_gatt_svc { 89 uint16_t start_handle; 90 uint16_t end_handle; 91 ble_uuid_any_t uuid; 92 }; 93 94 struct ble_gatt_attr { 95 uint16_t handle; 96 uint16_t offset; 97 struct os_mbuf *om; 98 }; 99 100 struct ble_gatt_chr { 101 uint16_t def_handle; 102 uint16_t val_handle; 103 uint8_t properties; 104 ble_uuid_any_t uuid; 105 }; 106 107 struct ble_gatt_dsc { 108 uint16_t handle; 109 ble_uuid_any_t uuid; 110 }; 111 112 typedef int ble_gatt_mtu_fn(uint16_t conn_handle, 113 const struct ble_gatt_error *error, 114 uint16_t mtu, void *arg); 115 typedef int ble_gatt_disc_svc_fn(uint16_t conn_handle, 116 const struct ble_gatt_error *error, 117 const struct ble_gatt_svc *service, 118 void *arg); 119 120 /** 121 * The host will free the attribute mbuf automatically after the callback is 122 * executed. The application can take ownership of the mbuf and prevent it 123 * from being freed by assigning NULL to attr->om. 124 */ 125 typedef int ble_gatt_attr_fn(uint16_t conn_handle, 126 const struct ble_gatt_error *error, 127 struct ble_gatt_attr *attr, 128 void *arg); 129 130 /** 131 * The host will free the attribute mbufs automatically after the callback is 132 * executed. The application can take ownership of the mbufs and prevent them 133 * from being freed by assigning NULL to each attribute's om field. 134 */ 135 typedef int ble_gatt_reliable_attr_fn(uint16_t conn_handle, 136 const struct ble_gatt_error *error, 137 struct ble_gatt_attr *attrs, 138 uint8_t num_attrs, void *arg); 139 140 typedef int ble_gatt_chr_fn(uint16_t conn_handle, 141 const struct ble_gatt_error *error, 142 const struct ble_gatt_chr *chr, void *arg); 143 144 typedef int ble_gatt_dsc_fn(uint16_t conn_handle, 145 const struct ble_gatt_error *error, 146 uint16_t chr_val_handle, 147 const struct ble_gatt_dsc *dsc, 148 void *arg); 149 150 /** 151 * Initiates GATT procedure: Exchange MTU. 152 * 153 * @param conn_handle The connection over which to execute the 154 * procedure. 155 * @param cb The function to call to report procedure status 156 * updates; null for no callback. 157 * @param cb_arg The optional argument to pass to the callback 158 * function. 159 * 160 * @return 0 on success; nonzero on failure. 161 */ 162 int ble_gattc_exchange_mtu(uint16_t conn_handle, 163 ble_gatt_mtu_fn *cb, void *cb_arg); 164 165 /** 166 * Initiates GATT procedure: Discover All Primary Services. 167 * 168 * @param conn_handle The connection over which to execute the 169 * procedure. 170 * @param cb The function to call to report procedure status 171 * updates; null for no callback. 172 * @param cb_arg The optional argument to pass to the callback 173 * function. 174 */ 175 int ble_gattc_disc_all_svcs(uint16_t conn_handle, 176 ble_gatt_disc_svc_fn *cb, void *cb_arg); 177 178 /** 179 * Initiates GATT procedure: Discover Primary Service by Service UUID. 180 * 181 * @param conn_handle The connection over which to execute the 182 * procedure. 183 * @param service_uuid128 The 128-bit UUID of the service to discover. 184 * @param cb The function to call to report procedure status 185 * updates; null for no callback. 186 * @param cb_arg The optional argument to pass to the callback 187 * function. 188 * 189 * @return 0 on success; nonzero on failure. 190 */ 191 int ble_gattc_disc_svc_by_uuid(uint16_t conn_handle, const ble_uuid_t *uuid, 192 ble_gatt_disc_svc_fn *cb, void *cb_arg); 193 194 /** 195 * Initiates GATT procedure: Find Included Services. 196 * 197 * @param conn_handle The connection over which to execute the 198 * procedure. 199 * @param start_handle The handle to begin the search at (generally 200 * the service definition handle). 201 * @param end_handle The handle to end the search at (generally the 202 * last handle in the service). 203 * @param cb The function to call to report procedure status 204 * updates; null for no callback. 205 * @param cb_arg The optional argument to pass to the callback 206 * function. 207 * 208 * @return 0 on success; nonzero on failure. 209 */ 210 int ble_gattc_find_inc_svcs(uint16_t conn_handle, uint16_t start_handle, 211 uint16_t end_handle, 212 ble_gatt_disc_svc_fn *cb, void *cb_arg); 213 214 /** 215 * Initiates GATT procedure: Discover All Characteristics of a Service. 216 * 217 * @param conn_handle The connection over which to execute the 218 * procedure. 219 * @param start_handle The handle to begin the search at (generally 220 * the service definition handle). 221 * @param end_handle The handle to end the search at (generally the 222 * last handle in the service). 223 * @param cb The function to call to report procedure status 224 * updates; null for no callback. 225 * @param cb_arg The optional argument to pass to the callback 226 * function. 227 * 228 * @return 0 on success; nonzero on failure. 229 */ 230 int ble_gattc_disc_all_chrs(uint16_t conn_handle, uint16_t start_handle, 231 uint16_t end_handle, ble_gatt_chr_fn *cb, 232 void *cb_arg); 233 234 /** 235 * Initiates GATT procedure: Discover Characteristics by UUID. 236 * 237 * @param conn_handle The connection over which to execute the 238 * procedure. 239 * @param start_handle The handle to begin the search at (generally 240 * the service definition handle). 241 * @param end_handle The handle to end the search at (generally the 242 * last handle in the service). 243 * @param chr_uuid128 The 128-bit UUID of the characteristic to 244 * discover. 245 * @param cb The function to call to report procedure status 246 * updates; null for no callback. 247 * @param cb_arg The optional argument to pass to the callback 248 * function. 249 * 250 * @return 0 on success; nonzero on failure. 251 */ 252 int ble_gattc_disc_chrs_by_uuid(uint16_t conn_handle, uint16_t start_handle, 253 uint16_t end_handle, const ble_uuid_t *uuid, 254 ble_gatt_chr_fn *cb, void *cb_arg); 255 256 /** 257 * Initiates GATT procedure: Discover All Characteristic Descriptors. 258 * 259 * @param conn_handle The connection over which to execute the 260 * procedure. 261 * @param chr_val_handle The handle of the characteristic value 262 * attribute. 263 * @param chr_end_handle The last handle in the characteristic 264 * definition. 265 * @param cb The function to call to report procedure status 266 * updates; null for no callback. 267 * @param cb_arg The optional argument to pass to the callback 268 * function. 269 * 270 * @return 0 on success; nonzero on failure. 271 */ 272 int ble_gattc_disc_all_dscs(uint16_t conn_handle, uint16_t start_handle, 273 uint16_t end_handle, 274 ble_gatt_dsc_fn *cb, void *cb_arg); 275 276 /** 277 * Initiates GATT procedure: Read Characteristic Value. 278 * 279 * @param conn_handle The connection over which to execute the 280 * procedure. 281 * @param attr_handle The handle of the characteristic value to read. 282 * @param cb The function to call to report procedure status 283 * updates; null for no callback. 284 * @param cb_arg The optional argument to pass to the callback 285 * function. 286 * 287 * @return 0 on success; nonzero on failure. 288 */ 289 int ble_gattc_read(uint16_t conn_handle, uint16_t attr_handle, 290 ble_gatt_attr_fn *cb, void *cb_arg); 291 292 /** 293 * Initiates GATT procedure: Read Using Characteristic UUID. 294 * 295 * @param conn_handle The connection over which to execute the 296 * procedure. 297 * @param start_handle The first handle to search (generally the 298 * handle of the service definition). 299 * @param end_handle The last handle to search (generally the 300 * last handle in the service definition). 301 * @param cb The function to call to report procedure status 302 * updates; null for no callback. 303 * @param cb_arg The optional argument to pass to the callback 304 * function. 305 * 306 * @return 0 on success; nonzero on failure. 307 */ 308 int ble_gattc_read_by_uuid(uint16_t conn_handle, uint16_t start_handle, 309 uint16_t end_handle, const ble_uuid_t *uuid, 310 ble_gatt_attr_fn *cb, void *cb_arg); 311 312 /** 313 * Initiates GATT procedure: Read Long Characteristic Values. 314 * 315 * @param conn_handle The connection over which to execute the 316 * procedure. 317 * @param handle The handle of the characteristic value to read. 318 * @param cb The function to call to report procedure status 319 * updates; null for no callback. 320 * @param cb_arg The optional argument to pass to the callback 321 * function. 322 * 323 * @return 0 on success; nonzero on failure. 324 */ 325 int ble_gattc_read_long(uint16_t conn_handle, uint16_t handle, uint16_t offset, 326 ble_gatt_attr_fn *cb, void *cb_arg); 327 328 /** 329 * Initiates GATT procedure: Read Multiple Characteristic Values. 330 * 331 * @param conn_handle The connection over which to execute the 332 * procedure. 333 * @param handles An array of 16-bit attribute handles to read. 334 * @param num_handles The number of entries in the "handles" array. 335 * @param cb The function to call to report procedure status 336 * updates; null for no callback. 337 * @param cb_arg The optional argument to pass to the callback 338 * function. 339 * 340 * @return 0 on success; nonzero on failure. 341 */ 342 int ble_gattc_read_mult(uint16_t conn_handle, const uint16_t *handles, 343 uint8_t num_handles, ble_gatt_attr_fn *cb, 344 void *cb_arg); 345 346 /** 347 * Initiates GATT procedure: Write Without Response. This function consumes 348 * the supplied mbuf regardless of the outcome. 349 * 350 * @param conn_handle The connection over which to execute the 351 * procedure. 352 * @param attr_handle The handle of the characteristic value to write 353 * to. 354 * @param txom The value to write to the characteristic. 355 * 356 * @return 0 on success; nonzero on failure. 357 */ 358 int ble_gattc_write_no_rsp(uint16_t conn_handle, uint16_t attr_handle, 359 struct os_mbuf *om); 360 361 /** 362 * Initiates GATT procedure: Write Without Response. This function consumes 363 * the supplied mbuf regardless of the outcome. 364 * 365 * @param conn_handle The connection over which to execute the 366 * procedure. 367 * @param attr_handle The handle of the characteristic value to write 368 * to. 369 * @param value The value to write to the characteristic. 370 * @param value_len The number of bytes to write. 371 * 372 * @return 0 on success; nonzero on failure. 373 */ 374 int ble_gattc_write_no_rsp_flat(uint16_t conn_handle, uint16_t attr_handle, 375 const void *data, uint16_t data_len); 376 377 /** 378 * Initiates GATT procedure: Write Characteristic Value. This function 379 * consumes the supplied mbuf regardless of the outcome. 380 * 381 * @param conn_handle The connection over which to execute the 382 * procedure. 383 * @param attr_handle The handle of the characteristic value to write 384 * to. 385 * @param txom The value to write to the characteristic. 386 * @param cb The function to call to report procedure status 387 * updates; null for no callback. 388 * @param cb_arg The optional argument to pass to the callback 389 * function. 390 * 391 * @return 0 on success; nonzero on failure. 392 */ 393 int ble_gattc_write(uint16_t conn_handle, uint16_t attr_handle, 394 struct os_mbuf *om, 395 ble_gatt_attr_fn *cb, void *cb_arg); 396 397 /** 398 * Initiates GATT procedure: Write Characteristic Value (flat buffer version). 399 * 400 * @param conn_handle The connection over which to execute the 401 * procedure. 402 * @param attr_handle The handle of the characteristic value to write 403 * to. 404 * @param value The value to write to the characteristic. 405 * @param value_len The number of bytes to write. 406 * @param cb The function to call to report procedure status 407 * updates; null for no callback. 408 * @param cb_arg The optional argument to pass to the callback 409 * function. 410 * 411 * @return 0 on success; nonzero on failure. 412 */ 413 int ble_gattc_write_flat(uint16_t conn_handle, uint16_t attr_handle, 414 const void *data, uint16_t data_len, 415 ble_gatt_attr_fn *cb, void *cb_arg); 416 417 /** 418 * Initiates GATT procedure: Write Long Characteristic Values. This function 419 * consumes the supplied mbuf regardless of the outcome. 420 * 421 * @param conn_handle The connection over which to execute the 422 * procedure. 423 * @param attr_handle The handle of the characteristic value to write 424 * to. 425 * @param txom The value to write to the characteristic. 426 * @param cb The function to call to report procedure status 427 * updates; null for no callback. 428 * @param cb_arg The optional argument to pass to the callback 429 * function. 430 * 431 * @return 0 on success; nonzero on failure. 432 */ 433 int ble_gattc_write_long(uint16_t conn_handle, uint16_t attr_handle, 434 uint16_t offset, struct os_mbuf *om, 435 ble_gatt_attr_fn *cb, void *cb_arg); 436 437 /** 438 * Initiates GATT procedure: Reliable Writes. This function consumes the 439 * supplied mbufs regardless of the outcome. 440 * 441 * @param conn_handle The connection over which to execute the 442 * procedure. 443 * @param attrs An array of attribute descriptors; specifies 444 * which characteristics to write to and what 445 * data to write to them. The mbuf pointer in 446 * each attribute is set to NULL by this 447 * function. 448 * @param num_attrs The number of characteristics to write; equal 449 * to the number of elements in the 'attrs' 450 * array. 451 * @param cb The function to call to report procedure status 452 * updates; null for no callback. 453 * @param cb_arg The optional argument to pass to the callback 454 * function. 455 */ 456 int ble_gattc_write_reliable(uint16_t conn_handle, 457 struct ble_gatt_attr *attrs, 458 int num_attrs, ble_gatt_reliable_attr_fn *cb, 459 void *cb_arg); 460 461 /** 462 * Sends a "free-form" characteristic notification. This function consumes the 463 * supplied mbuf regardless of the outcome. 464 * 465 * @param conn_handle The connection over which to execute the 466 * procedure. 467 * @param chr_val_handle The attribute handle to indicate in the 468 * outgoing notification. 469 * @param txom The value to write to the characteristic. 470 * 471 * @return 0 on success; nonzero on failure. 472 */ 473 int ble_gattc_notify_custom(uint16_t conn_handle, uint16_t att_handle, 474 struct os_mbuf *om); 475 476 /** 477 * Sends a characteristic notification. The content of the message is read 478 * from the specified characteristic. 479 * 480 * @param conn_handle The connection over which to execute the 481 * procedure. 482 * @param chr_val_handle The value attribute handle of the 483 * characteristic to include in the outgoing 484 * notification. 485 * 486 * @return 0 on success; nonzero on failure. 487 */ 488 int ble_gattc_notify(uint16_t conn_handle, uint16_t chr_val_handle); 489 490 /** 491 * Sends a "free-form" characteristic indication. The provided mbuf contains 492 * the indication payload. This function consumes the supplied mbuf regardless 493 * of the outcome. 494 * 495 * @param conn_handle The connection over which to execute the 496 * procedure. 497 * @param chr_val_handle The value attribute handle of the 498 * characteristic to include in the outgoing 499 * indication. 500 * @param txom The data to include in the indication. 501 * 502 * @return 0 on success; nonzero on failure. 503 */ 504 int ble_gattc_indicate_custom(uint16_t conn_handle, uint16_t chr_val_handle, 505 struct os_mbuf *txom); 506 507 /** 508 * Sends a characteristic indication. The content of the message is read from 509 * the specified characteristic. 510 * 511 * @param conn_handle The connection over which to execute the 512 * procedure. 513 * @param chr_val_handle The value attribute handle of the 514 * characteristic to include in the outgoing 515 * indication. 516 * 517 * @return 0 on success; nonzero on failure. 518 */ 519 int ble_gattc_indicate(uint16_t conn_handle, uint16_t chr_val_handle); 520 521 int ble_gattc_init(void); 522 523 /*** @server. */ 524 525 struct ble_gatt_access_ctxt; 526 typedef int ble_gatt_access_fn(uint16_t conn_handle, uint16_t attr_handle, 527 struct ble_gatt_access_ctxt *ctxt, void *arg); 528 529 typedef uint16_t ble_gatt_chr_flags; 530 531 struct ble_gatt_chr_def { 532 /** 533 * Pointer to characteristic UUID; use BLE_UUIDxx_DECLARE macros to declare 534 * proper UUID; NULL if there are no more characteristics in the service. 535 */ 536 const ble_uuid_t *uuid; 537 538 /** 539 * Callback that gets executed when this characteristic is read or 540 * written. 541 */ 542 ble_gatt_access_fn *access_cb; 543 544 /** Optional argument for callback. */ 545 void *arg; 546 547 /** 548 * Array of this characteristic's descriptors. NULL if no descriptors. 549 * Do not include CCCD; it gets added automatically if this 550 * characteristic's notify or indicate flag is set. 551 */ 552 struct ble_gatt_dsc_def *descriptors; 553 554 /** Specifies the set of permitted operations for this characteristic. */ 555 ble_gatt_chr_flags flags; 556 557 /** Specifies minimum required key size to access this characteristic. */ 558 uint8_t min_key_size; 559 560 /** 561 * At registration time, this is filled in with the characteristic's value 562 * attribute handle. 563 */ 564 uint16_t *val_handle; 565 }; 566 567 struct ble_gatt_svc_def { 568 /** 569 * One of the following: 570 * o BLE_GATT_SVC_TYPE_PRIMARY - primary service 571 * o BLE_GATT_SVC_TYPE_SECONDARY - secondary service 572 * o 0 - No more services in this array. 573 */ 574 uint8_t type; 575 576 /** 577 * Pointer to service UUID; use BLE_UUIDxx_DECLARE macros to declare 578 * proper UUID; NULL if there are no more characteristics in the service. 579 */ 580 const ble_uuid_t *uuid; 581 582 /** 583 * Array of pointers to other service definitions. These services are 584 * reported as "included services" during service discovery. Terminate the 585 * array with NULL. 586 */ 587 const struct ble_gatt_svc_def **includes; 588 589 /** 590 * Array of characteristic definitions corresponding to characteristics 591 * belonging to this service. 592 */ 593 const struct ble_gatt_chr_def *characteristics; 594 }; 595 596 struct ble_gatt_dsc_def { 597 /** 598 * Pointer to descriptor UUID; use BLE_UUIDxx_DECLARE macros to declare 599 * proper UUID; NULL if there are no more characteristics in the service. 600 */ 601 const ble_uuid_t *uuid; 602 603 /** Specifies the set of permitted operations for this descriptor. */ 604 uint8_t att_flags; 605 606 /** Specifies minimum required key size to access this descriptor. */ 607 uint8_t min_key_size; 608 609 /** Callback that gets executed when the descriptor is read or written. */ 610 ble_gatt_access_fn *access_cb; 611 612 /** Optional argument for callback. */ 613 void *arg; 614 }; 615 616 /** 617 * Context for an access to a GATT characteristic or descriptor. When a client 618 * reads or writes a locally registered characteristic or descriptor, an 619 * instance of this struct gets passed to the application callback. 620 */ 621 struct ble_gatt_access_ctxt { 622 /** 623 * Indicates the gatt operation being performed. This is equal to one of 624 * the following values: 625 * o BLE_GATT_ACCESS_OP_READ_CHR 626 * o BLE_GATT_ACCESS_OP_WRITE_CHR 627 * o BLE_GATT_ACCESS_OP_READ_DSC 628 * o BLE_GATT_ACCESS_OP_WRITE_DSC 629 */ 630 uint8_t op; 631 632 /** 633 * A container for the GATT access data. 634 * o For reads: The application populates this with the value of the 635 * characteristic or descriptor being read. 636 * o For writes: This is already populated with the value being written 637 * by the peer. If the application wishes to retain this mbuf for 638 * later use, the access callback must set this pointer to NULL to 639 * prevent the stack from freeing it. 640 */ 641 struct os_mbuf *om; 642 643 /** 644 * The GATT operation being performed dictates which field in this union is 645 * valid. If a characteristic is being accessed, the chr field is valid. 646 * Otherwise a descriptor is being accessed, in which case the dsc field 647 * is valid. 648 */ 649 union { 650 /** 651 * The characteristic definition corresponding to the characteristic 652 * being accessed. This is what the app registered at startup. 653 */ 654 const struct ble_gatt_chr_def *chr; 655 656 /** 657 * The descriptor definition corresponding to the descriptor being 658 * accessed. This is what the app registered at startup. 659 */ 660 const struct ble_gatt_dsc_def *dsc; 661 }; 662 }; 663 664 /** 665 * Context passed to the registration callback; represents the GATT service, 666 * characteristic, or descriptor being registered. 667 */ 668 struct ble_gatt_register_ctxt { 669 /** 670 * Indicates the gatt registration operation just performed. This is 671 * equal to one of the following values: 672 * o BLE_GATT_REGISTER_OP_SVC 673 * o BLE_GATT_REGISTER_OP_CHR 674 * o BLE_GATT_REGISTER_OP_DSC 675 */ 676 uint8_t op; 677 678 /** 679 * The value of the op field determines which field in this union is valid. 680 */ 681 union { 682 /** Service; valid if op == BLE_GATT_REGISTER_OP_SVC. */ 683 struct { 684 /** The ATT handle of the service definition attribute. */ 685 uint16_t handle; 686 687 /** 688 * The service definition representing the service being 689 * registered. 690 */ 691 const struct ble_gatt_svc_def *svc_def; 692 } svc; 693 694 /** Characteristic; valid if op == BLE_GATT_REGISTER_OP_CHR. */ 695 struct { 696 /** The ATT handle of the characteristic definition attribute. */ 697 uint16_t def_handle; 698 699 /** The ATT handle of the characteristic value attribute. */ 700 uint16_t val_handle; 701 702 /** 703 * The characteristic definition representing the characteristic 704 * being registered. 705 */ 706 const struct ble_gatt_chr_def *chr_def; 707 708 /** 709 * The service definition corresponding to the characteristic's 710 * parent service. 711 */ 712 const struct ble_gatt_svc_def *svc_def; 713 } chr; 714 715 /** Descriptor; valid if op == BLE_GATT_REGISTER_OP_DSC. */ 716 struct { 717 /** The ATT handle of the descriptor definition attribute. */ 718 uint16_t handle; 719 720 /** 721 * The descriptor definition corresponding to the descriptor being 722 * registered. 723 */ 724 const struct ble_gatt_dsc_def *dsc_def; 725 726 /** 727 * The characteristic definition corresponding to the descriptor's 728 * parent characteristic. 729 */ 730 const struct ble_gatt_chr_def *chr_def; 731 732 /** 733 * The service definition corresponding to the descriptor's 734 * grandparent service 735 */ 736 const struct ble_gatt_svc_def *svc_def; 737 } dsc; 738 }; 739 }; 740 741 typedef void ble_gatt_register_fn(struct ble_gatt_register_ctxt *ctxt, 742 void *arg); 743 744 /** 745 * Queues a set of service definitions for registration. All services queued 746 * in this manner get registered when ble_gatts_start() is called. 747 * 748 * @param svcs An array of service definitions to queue for 749 * registration. This array must be 750 * terminated with an entry whose 'type' 751 * equals 0. 752 * 753 * @return 0 on success; 754 * BLE_HS_ENOMEM on heap exhaustion. 755 */ 756 int ble_gatts_add_svcs(const struct ble_gatt_svc_def *svcs); 757 758 /** 759 * Set visibility of local GATT service. Invisible services are not removed 760 * from database but are not discoverable by peer devices. Service Changed 761 * should be handled by application when needed by calling 762 * ble_svc_gatt_changed(). 763 * 764 * @param handle Handle of service 765 * @param visible non-zero if service should be visible 766 * 767 * @return 0 on success; 768 * BLE_HS_ENOENT if service wasn't found. 769 */ 770 int ble_gatts_svc_set_visibility(uint16_t handle, int visible); 771 772 /** 773 * Adjusts a host configuration object's settings to accommodate the specified 774 * service definition array. This function adds the counts to the appropriate 775 * fields in the supplied configuration object without clearing them first, so 776 * it can be called repeatedly with different inputs to calculate totals. Be 777 * sure to zero the GATT server settings prior to the first call to this 778 * function. 779 * 780 * @param defs The service array containing the resource 781 * definitions to be counted. 782 * 783 * @return 0 on success; 784 * BLE_HS_EINVAL if the svcs array contains an 785 * invalid resource definition. 786 */ 787 int ble_gatts_count_cfg(const struct ble_gatt_svc_def *defs); 788 789 /** 790 * Send notification (or indication) to any connected devices that have 791 * subscribed for notification (or indication) for specified characteristic. 792 * 793 * @param chr_val_handle Characteristic value handle 794 */ 795 void ble_gatts_chr_updated(uint16_t chr_val_handle); 796 797 /** 798 * Retrieves the attribute handle associated with a local GATT service. 799 * 800 * @param uuid The UUID of the service to look up. 801 * @param out_handle On success, populated with the handle of the 802 * service attribute. Pass null if you don't 803 * need this value. 804 * 805 * @return 0 on success; 806 * BLE_HS_ENOENT if the specified service could 807 * not be found. 808 */ 809 int ble_gatts_find_svc(const ble_uuid_t *uuid, uint16_t *out_handle); 810 811 /** 812 * Retrieves the pair of attribute handles associated with a local GATT 813 * characteristic. 814 * 815 * @param svc_uuid The UUID of the parent service. 816 * @param chr_uuid The UUID of the characteristic to look up. 817 * @param out_def_handle On success, populated with the handle 818 * of the characteristic definition attribute. 819 * Pass null if you don't need this value. 820 * @param out_val_handle On success, populated with the handle 821 * of the characteristic value attribute. 822 * Pass null if you don't need this value. 823 * 824 * @return 0 on success; 825 * BLE_HS_ENOENT if the specified service or 826 * characteristic could not be found. 827 */ 828 int ble_gatts_find_chr(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, 829 uint16_t *out_def_handle, uint16_t *out_val_handle); 830 831 /** 832 * Retrieves the attribute handle associated with a local GATT descriptor. 833 * 834 * @param svc_uuid The UUID of the grandparent service. 835 * @param chr_uuid The UUID of the parent characteristic. 836 * @param dsc_uuid The UUID of the descriptor ro look up. 837 * @param out_handle On success, populated with the handle 838 * of the descriptor attribute. Pass null if 839 * you don't need this value. 840 * 841 * @return 0 on success; 842 * BLE_HS_ENOENT if the specified service, 843 * characteristic, or descriptor could not be 844 * found. 845 */ 846 int ble_gatts_find_dsc(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, 847 const ble_uuid_t *dsc_uuid, uint16_t *out_dsc_handle); 848 849 typedef void (*ble_gatt_svc_foreach_fn)(const struct ble_gatt_svc_def *svc, 850 uint16_t handle, 851 uint16_t end_group_handle, 852 void *arg); 853 854 /** 855 * Prints dump of local GATT database. This is useful to log local state of 856 * database in human readable form. 857 */ 858 void ble_gatts_show_local(void); 859 860 /** 861 * Resets the GATT server to its initial state. On success, this function 862 * removes all supported services, characteristics, and descriptors. This 863 * function requires that: 864 * o No peers are connected, and 865 * o No GAP operations are active (advertise, discover, or connect). 866 * 867 * @return 0 on success; 868 * BLE_HS_EBUSY if the GATT server could not be 869 * reset due to existing connections or active 870 * GAP procedures. 871 */ 872 int ble_gatts_reset(void); 873 874 /** 875 * Makes all registered services available to peers. This function gets called 876 * automatically by the NimBLE host on startup; manual calls are only necessary 877 * for replacing the set of supported services with a new one. This function 878 * requires that: 879 * o No peers are connected, and 880 * o No GAP operations are active (advertise, discover, or connect). 881 * 882 * @return 0 on success; 883 * A BLE host core return code on unexpected 884 * error. 885 */ 886 int ble_gatts_start(void); 887 void ble_gatts_stop(void); 888 889 #ifdef __cplusplus 890 } 891 #endif 892 893 /** 894 * @} 895 */ 896 897 #endif 898