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_GAP_ 21 #define H_BLE_GAP_ 22 23 /** 24 * @brief Bluetooth Host Generic Access Profile (GAP) 25 * @defgroup bt_host_gap Bluetooth Host Generic Access Profile (GAP) 26 * @ingroup bt_host 27 * @{ 28 */ 29 30 #include <stdint.h> 31 #include "host/ble_hs.h" 32 #include "host/ble_hs_adv.h" 33 #include "syscfg/syscfg.h" 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 struct hci_le_conn_complete; 40 struct hci_conn_update; 41 42 /** 30 ms. */ 43 #define BLE_GAP_ADV_FAST_INTERVAL1_MIN (30 * 1000 / BLE_HCI_ADV_ITVL) 44 45 /** 60 ms. */ 46 #define BLE_GAP_ADV_FAST_INTERVAL1_MAX (60 * 1000 / BLE_HCI_ADV_ITVL) 47 48 /** 100 ms. */ 49 #define BLE_GAP_ADV_FAST_INTERVAL2_MIN (100 * 1000 / BLE_HCI_ADV_ITVL) 50 51 /** 150 ms. */ 52 #define BLE_GAP_ADV_FAST_INTERVAL2_MAX (150 * 1000 / BLE_HCI_ADV_ITVL) 53 54 /** 30 ms; active scanning. */ 55 #define BLE_GAP_SCAN_FAST_INTERVAL_MIN (30 * 1000 / BLE_HCI_ADV_ITVL) 56 57 /** 60 ms; active scanning. */ 58 #define BLE_GAP_SCAN_FAST_INTERVAL_MAX (60 * 1000 / BLE_HCI_ADV_ITVL) 59 60 /** 11.25 ms; limited discovery interval. */ 61 #define BLE_GAP_LIM_DISC_SCAN_INT (11.25 * 1000 / BLE_HCI_SCAN_ITVL) 62 63 /** 11.25 ms; limited discovery window (not from the spec). */ 64 #define BLE_GAP_LIM_DISC_SCAN_WINDOW (11.25 * 1000 / BLE_HCI_SCAN_ITVL) 65 66 /** 30 ms; active scanning. */ 67 #define BLE_GAP_SCAN_FAST_WINDOW (30 * 1000 / BLE_HCI_SCAN_ITVL) 68 69 /* 30.72 seconds; active scanning. */ 70 #define BLE_GAP_SCAN_FAST_PERIOD (30.72 * 1000) 71 72 /** 1.28 seconds; background scanning. */ 73 #define BLE_GAP_SCAN_SLOW_INTERVAL1 (1280 * 1000 / BLE_HCI_SCAN_ITVL) 74 75 /** 11.25 ms; background scanning. */ 76 #define BLE_GAP_SCAN_SLOW_WINDOW1 (11.25 * 1000 / BLE_HCI_SCAN_ITVL) 77 78 /** 10.24 seconds. */ 79 #define BLE_GAP_DISC_DUR_DFLT (10.24 * 1000) 80 81 /** 30 seconds (not from the spec). */ 82 #define BLE_GAP_CONN_DUR_DFLT (30 * 1000) 83 84 /** 1 second. */ 85 #define BLE_GAP_CONN_PAUSE_CENTRAL (1 * 1000) 86 87 /** 5 seconds. */ 88 #define BLE_GAP_CONN_PAUSE_PERIPHERAL (5 * 1000) 89 90 /* 30 ms. */ 91 #define BLE_GAP_INITIAL_CONN_ITVL_MIN (30 * 1000 / BLE_HCI_CONN_ITVL) 92 93 /* 50 ms. */ 94 #define BLE_GAP_INITIAL_CONN_ITVL_MAX (50 * 1000 / BLE_HCI_CONN_ITVL) 95 96 /** Default channels mask: all three channels are used. */ 97 #define BLE_GAP_ADV_DFLT_CHANNEL_MAP 0x07 98 99 #define BLE_GAP_INITIAL_CONN_LATENCY 0 100 #define BLE_GAP_INITIAL_SUPERVISION_TIMEOUT 0x0100 101 #define BLE_GAP_INITIAL_CONN_MIN_CE_LEN 0x0010 102 #define BLE_GAP_INITIAL_CONN_MAX_CE_LEN 0x0300 103 104 #define BLE_GAP_ROLE_MASTER 0 105 #define BLE_GAP_ROLE_SLAVE 1 106 107 #define BLE_GAP_EVENT_CONNECT 0 108 #define BLE_GAP_EVENT_DISCONNECT 1 109 /* Reserved 2 */ 110 #define BLE_GAP_EVENT_CONN_UPDATE 3 111 #define BLE_GAP_EVENT_CONN_UPDATE_REQ 4 112 #define BLE_GAP_EVENT_L2CAP_UPDATE_REQ 5 113 #define BLE_GAP_EVENT_TERM_FAILURE 6 114 #define BLE_GAP_EVENT_DISC 7 115 #define BLE_GAP_EVENT_DISC_COMPLETE 8 116 #define BLE_GAP_EVENT_ADV_COMPLETE 9 117 #define BLE_GAP_EVENT_ENC_CHANGE 10 118 #define BLE_GAP_EVENT_PASSKEY_ACTION 11 119 #define BLE_GAP_EVENT_NOTIFY_RX 12 120 #define BLE_GAP_EVENT_NOTIFY_TX 13 121 #define BLE_GAP_EVENT_SUBSCRIBE 14 122 #define BLE_GAP_EVENT_MTU 15 123 #define BLE_GAP_EVENT_IDENTITY_RESOLVED 16 124 #define BLE_GAP_EVENT_REPEAT_PAIRING 17 125 #define BLE_GAP_EVENT_PHY_UPDATE_COMPLETE 18 126 #define BLE_GAP_EVENT_EXT_DISC 19 127 #define BLE_GAP_EVENT_PERIODIC_SYNC 20 128 #define BLE_GAP_EVENT_PERIODIC_REPORT 21 129 #define BLE_GAP_EVENT_PERIODIC_SYNC_LOST 22 130 #define BLE_GAP_EVENT_SCAN_REQ_RCVD 23 131 #define BLE_GAP_EVENT_PERIODIC_TRANSFER 24 132 #define BLE_GAP_EVENT_HOST_SHUTDOWN 31 133 134 /*** Reason codes for the subscribe GAP event. */ 135 136 /** Peer's CCCD subscription state changed due to a descriptor write. */ 137 #define BLE_GAP_SUBSCRIBE_REASON_WRITE 1 138 139 /** Peer's CCCD subscription state cleared due to connection termination. */ 140 #define BLE_GAP_SUBSCRIBE_REASON_TERM 2 141 142 /** 143 * Peer's CCCD subscription state changed due to restore from persistence 144 * (bonding restored). 145 */ 146 #define BLE_GAP_SUBSCRIBE_REASON_RESTORE 3 147 148 #define BLE_GAP_REPEAT_PAIRING_RETRY 1 149 #define BLE_GAP_REPEAT_PAIRING_IGNORE 2 150 151 /** Connection security state */ 152 struct ble_gap_sec_state { 153 /** If connection is encrypted */ 154 unsigned encrypted : 1; 155 156 /** If connection is authenticated */ 157 unsigned authenticated : 1; 158 159 /** If connection is bonded (security information is stored) */ 160 unsigned bonded : 1; 161 162 /** Size of a key used for encryption */ 163 unsigned key_size : 5; 164 }; 165 166 /** Advertising parameters */ 167 struct ble_gap_adv_params { 168 /** Advertising mode. Can be one of following constants: 169 * - BLE_GAP_CONN_MODE_NON (non-connectable; 3.C.9.3.2). 170 * - BLE_GAP_CONN_MODE_DIR (directed-connectable; 3.C.9.3.3). 171 * - BLE_GAP_CONN_MODE_UND (undirected-connectable; 3.C.9.3.4). 172 */ 173 uint8_t conn_mode; 174 /** Discoverable mode. Can be one of following constants: 175 * - BLE_GAP_DISC_MODE_NON (non-discoverable; 3.C.9.2.2). 176 * - BLE_GAP_DISC_MODE_LTD (limited-discoverable; 3.C.9.2.3). 177 * - BLE_GAP_DISC_MODE_GEN (general-discoverable; 3.C.9.2.4). 178 */ 179 uint8_t disc_mode; 180 181 /** Minimum advertising interval, if 0 stack use sane defaults */ 182 uint16_t itvl_min; 183 /** Maximum advertising interval, if 0 stack use sane defaults */ 184 uint16_t itvl_max; 185 /** Advertising channel map , if 0 stack use sane defaults */ 186 uint8_t channel_map; 187 188 /** Advertising Filter policy */ 189 uint8_t filter_policy; 190 191 /** If do High Duty cycle for Directed Advertising */ 192 uint8_t high_duty_cycle : 1; 193 }; 194 195 /** @brief Connection descriptor */ 196 struct ble_gap_conn_desc { 197 /** Connection security state */ 198 struct ble_gap_sec_state sec_state; 199 200 /** Local identity address */ 201 ble_addr_t our_id_addr; 202 203 /** Peer identity address */ 204 ble_addr_t peer_id_addr; 205 206 /** Local over-the-air address */ 207 ble_addr_t our_ota_addr; 208 209 /** Peer over-the-air address */ 210 ble_addr_t peer_ota_addr; 211 212 /** Connection handle */ 213 uint16_t conn_handle; 214 215 /** Connection interval */ 216 uint16_t conn_itvl; 217 218 /** Connection latency */ 219 uint16_t conn_latency; 220 221 /** Connection supervision timeout */ 222 uint16_t supervision_timeout; 223 224 /** Connection Role 225 * Possible values BLE_GAP_ROLE_SLAVE or BLE_GAP_ROLE_MASTER 226 */ 227 uint8_t role; 228 229 /** Master clock accuracy */ 230 uint8_t master_clock_accuracy; 231 }; 232 233 /** @brief Connection parameters */ 234 struct ble_gap_conn_params { 235 /** Scan interval in 0.625ms units */ 236 uint16_t scan_itvl; 237 238 /** Scan window in 0.625ms units */ 239 uint16_t scan_window; 240 241 /** Minimum value for connection interval in 1.25ms units */ 242 uint16_t itvl_min; 243 244 /** Maximum value for connection interval in 1.25ms units */ 245 uint16_t itvl_max; 246 247 /** Connection latency */ 248 uint16_t latency; 249 250 /** Supervision timeout in 10ms units */ 251 uint16_t supervision_timeout; 252 253 /** Minimum length of connection event in 0.625ms units */ 254 uint16_t min_ce_len; 255 256 /** Maximum length of connection event in 0.625ms units */ 257 uint16_t max_ce_len; 258 }; 259 260 /** @brief Extended discovery parameters */ 261 struct ble_gap_ext_disc_params { 262 /** Scan interval in 0.625ms units */ 263 uint16_t itvl; 264 265 /** Scan window in 0.625ms units */ 266 uint16_t window; 267 268 /** If passive scan should be used */ 269 uint8_t passive : 1; 270 }; 271 272 /** @brief Discovery parameters */ 273 struct ble_gap_disc_params { 274 /** Scan interval in 0.625ms units */ 275 uint16_t itvl; 276 277 /** Scan window in 0.625ms units */ 278 uint16_t window; 279 280 /** Scan filter policy */ 281 uint8_t filter_policy; 282 283 /** If limited discovery procedure should be used */ 284 uint8_t limited : 1; 285 286 /** If passive scan should be used */ 287 uint8_t passive : 1; 288 289 /** If enable duplicates filtering */ 290 uint8_t filter_duplicates : 1; 291 }; 292 293 /** @brief Connection parameters update parameters */ 294 struct ble_gap_upd_params { 295 /** Minimum value for connection interval in 1.25ms units */ 296 uint16_t itvl_min; 297 298 /** Maximum value for connection interval in 1.25ms units */ 299 uint16_t itvl_max; 300 301 /** Connection latency */ 302 uint16_t latency; 303 304 /** Supervision timeout in 10ms units */ 305 uint16_t supervision_timeout; 306 307 /** Minimum length of connection event in 0.625ms units */ 308 uint16_t min_ce_len; 309 310 /** Maximum length of connection event in 0.625ms units */ 311 uint16_t max_ce_len; 312 }; 313 314 /** @brief Passkey query */ 315 struct ble_gap_passkey_params { 316 /** Passkey action, can be one of following constants: 317 * - BLE_SM_IOACT_NONE 318 * - BLE_SM_IOACT_OOB 319 * - BLE_SM_IOACT_INPUT 320 * - BLE_SM_IOACT_DISP 321 * - BLE_SM_IOACT_NUMCMP 322 */ 323 uint8_t action; 324 325 /** Passkey to compare, valid for BLE_SM_IOACT_NUMCMP action */ 326 uint32_t numcmp; 327 }; 328 329 #if MYNEWT_VAL(BLE_EXT_ADV) 330 331 #define BLE_GAP_EXT_ADV_DATA_STATUS_COMPLETE 0x00 332 #define BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE 0x01 333 #define BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED 0x02 334 335 /** @brief Extended advertising report */ 336 struct ble_gap_ext_disc_desc { 337 /** Report properties bitmask 338 * - BLE_HCI_ADV_CONN_MASK 339 * - BLE_HCI_ADV_SCAN_MASK 340 * - BLE_HCI_ADV_DIRECT_MASK 341 * - BLE_HCI_ADV_SCAN_RSP_MASK 342 * - BLE_HCI_ADV_LEGACY_MASK 343 * */ 344 uint8_t props; 345 346 /** Advertising data status, can be one of following constants: 347 * - BLE_GAP_EXT_ADV_DATA_STATUS_COMPLETE 348 * - BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE 349 * - BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED 350 */ 351 uint8_t data_status; 352 353 /** Legacy advertising PDU type. Valid if BLE_HCI_ADV_LEGACY_MASK props is 354 * set. Can be one of following constants: 355 * - BLE_HCI_ADV_RPT_EVTYPE_ADV_IND 356 * - BLE_HCI_ADV_RPT_EVTYPE_DIR_IND 357 * - BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND 358 * - BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND 359 * - BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP 360 */ 361 uint8_t legacy_event_type; 362 363 /** Advertiser address */ 364 ble_addr_t addr; 365 366 /** Received signal strength indication in dBm (127 if unavailable) */ 367 int8_t rssi; 368 369 /** Advertiser transmit power in dBm (127 if unavailable) */ 370 int8_t tx_power; 371 372 /** Advertising Set ID */ 373 uint8_t sid; 374 375 /** Primary advertising PHY, can be one of following constants: 376 * - BLE_HCI_LE_PHY_1M 377 * - BLE_HCI_LE_PHY_CODED 378 */ 379 uint8_t prim_phy; 380 381 /** Secondary advertising PHY, can be one of following constants: 382 * - BLE_HCI_LE_PHY_1M 383 * - LE_HCI_LE_PHY_2M 384 * - BLE_HCI_LE_PHY_CODED 385 */ 386 uint8_t sec_phy; 387 388 /** Periodic advertising interval. 0 if no periodic advertising. */ 389 uint16_t periodic_adv_itvl; 390 391 /** Advertising Data length */ 392 uint8_t length_data; 393 394 /** Advertising data */ 395 const uint8_t *data; 396 397 /** Directed advertising address. Valid if BLE_HCI_ADV_DIRECT_MASK props is 398 * set (BLE_ADDR_ANY otherwise). 399 */ 400 ble_addr_t direct_addr; 401 }; 402 #endif 403 404 /** @brief Advertising report */ 405 struct ble_gap_disc_desc { 406 /** Advertising PDU type. Can be one of following constants: 407 * - BLE_HCI_ADV_RPT_EVTYPE_ADV_IND 408 * - BLE_HCI_ADV_RPT_EVTYPE_DIR_IND 409 * - BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND 410 * - BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND 411 * - BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP 412 */ 413 uint8_t event_type; 414 415 /** Advertising Data length */ 416 uint8_t length_data; 417 418 /** Advertiser address */ 419 ble_addr_t addr; 420 421 /** Received signal strength indication in dBm (127 if unavailable) */ 422 int8_t rssi; 423 424 /** Advertising data */ 425 const uint8_t *data; 426 427 /** Directed advertising address. Valid for BLE_HCI_ADV_RPT_EVTYPE_DIR_IND 428 * event type (BLE_ADDR_ANY otherwise). 429 */ 430 ble_addr_t direct_addr; 431 }; 432 433 struct ble_gap_repeat_pairing { 434 /** The handle of the relevant connection. */ 435 uint16_t conn_handle; 436 437 /** Properties of the existing bond. */ 438 uint8_t cur_key_size; 439 uint8_t cur_authenticated : 1; 440 uint8_t cur_sc : 1; 441 442 /** 443 * Properties of the imminent secure link if the pairing procedure is 444 * allowed to continue. 445 */ 446 uint8_t new_key_size; 447 uint8_t new_authenticated : 1; 448 uint8_t new_sc : 1; 449 uint8_t new_bonding : 1; 450 }; 451 452 /** 453 * Represents a GAP-related event. When such an event occurs, the host 454 * notifies the application by passing an instance of this structure to an 455 * application-specified callback. 456 */ 457 struct ble_gap_event { 458 /** 459 * Indicates the type of GAP event that occurred. This is one of the 460 * BLE_GAP_EVENT codes. 461 */ 462 uint8_t type; 463 464 /** 465 * A discriminated union containing additional details concerning the GAP 466 * event. The 'type' field indicates which member of the union is valid. 467 */ 468 union { 469 /** 470 * Represents a connection attempt. Valid for the following event 471 * types: 472 * o BLE_GAP_EVENT_CONNECT 473 */ 474 struct { 475 /** 476 * The status of the connection attempt; 477 * o 0: the connection was successfully established. 478 * o BLE host error code: the connection attempt failed for 479 * the specified reason. 480 */ 481 int status; 482 483 /** The handle of the relevant connection. */ 484 uint16_t conn_handle; 485 } connect; 486 487 /** 488 * Represents a terminated connection. Valid for the following event 489 * types: 490 * o BLE_GAP_EVENT_DISCONNECT 491 */ 492 struct { 493 /** 494 * A BLE host return code indicating the reason for the 495 * disconnect. 496 */ 497 int reason; 498 499 /** Information about the connection prior to termination. */ 500 struct ble_gap_conn_desc conn; 501 } disconnect; 502 503 /** 504 * Represents an advertising report received during a discovery 505 * procedure. Valid for the following event types: 506 * o BLE_GAP_EVENT_DISC 507 */ 508 struct ble_gap_disc_desc disc; 509 510 #if MYNEWT_VAL(BLE_EXT_ADV) 511 /** 512 * Represents an extended advertising report received during a discovery 513 * procedure. Valid for the following event types: 514 * o BLE_GAP_EVENT_EXT_DISC 515 */ 516 struct ble_gap_ext_disc_desc ext_disc; 517 #endif 518 519 /** 520 * Represents a completed discovery procedure. Valid for the following 521 * event types: 522 * o BLE_GAP_EVENT_DISC_COMPLETE 523 */ 524 struct { 525 /** 526 * The reason the discovery procedure stopped. Typical reason 527 * codes are: 528 * o 0: Duration expired. 529 * o BLE_HS_EPREEMPTED: Host aborted procedure to configure a 530 * peer's identity. 531 */ 532 int reason; 533 } disc_complete; 534 535 /** 536 * Represents a completed advertise procedure. Valid for the following 537 * event types: 538 * o BLE_GAP_EVENT_ADV_COMPLETE 539 */ 540 struct { 541 /** 542 * The reason the advertise procedure stopped. Typical reason 543 * codes are: 544 * o 0: Terminated due to connection. 545 * o BLE_HS_ETIMEOUT: Duration expired. 546 * o BLE_HS_EPREEMPTED: Host aborted procedure to configure a 547 * peer's identity. 548 */ 549 int reason; 550 551 #if MYNEWT_VAL(BLE_EXT_ADV) 552 /** Advertising instance */ 553 uint8_t instance; 554 /** The handle of the relevant connection - valid if reason=0 */ 555 uint16_t conn_handle; 556 /** 557 * Number of completed extended advertising events 558 * 559 * This field is only valid if non-zero max_events was passed to 560 * ble_gap_ext_adv_start() and advertising completed due to duration 561 * timeout or max events transmitted. 562 * */ 563 uint8_t num_ext_adv_events; 564 #endif 565 } adv_complete; 566 567 /** 568 * Represents an attempt to update a connection's parameters. If the 569 * attempt was successful, the connection's descriptor reflects the 570 * updated parameters. 571 * 572 * Valid for the following event types: 573 * o BLE_GAP_EVENT_CONN_UPDATE 574 */ 575 struct { 576 /** 577 * The result of the connection update attempt; 578 * o 0: the connection was successfully updated. 579 * o BLE host error code: the connection update attempt failed 580 * for the specified reason. 581 */ 582 int status; 583 584 /** The handle of the relevant connection. */ 585 uint16_t conn_handle; 586 } conn_update; 587 588 /** 589 * Represents a peer's request to update the connection parameters. 590 * This event is generated when a peer performs any of the following 591 * procedures: 592 * o L2CAP Connection Parameter Update Procedure 593 * o Link-Layer Connection Parameters Request Procedure 594 * 595 * To reject the request, return a non-zero HCI error code. The value 596 * returned is the reject reason given to the controller. 597 * 598 * Valid for the following event types: 599 * o BLE_GAP_EVENT_L2CAP_UPDATE_REQ 600 * o BLE_GAP_EVENT_CONN_UPDATE_REQ 601 */ 602 struct { 603 /** 604 * Indicates the connection parameters that the peer would like to 605 * use. 606 */ 607 const struct ble_gap_upd_params *peer_params; 608 609 /** 610 * Indicates the connection parameters that the local device would 611 * like to use. The application callback should fill this in. By 612 * default, this struct contains the requested parameters (i.e., 613 * it is a copy of 'peer_params'). 614 */ 615 struct ble_gap_upd_params *self_params; 616 617 /** The handle of the relevant connection. */ 618 uint16_t conn_handle; 619 } conn_update_req; 620 621 /** 622 * Represents a failed attempt to terminate an established connection. 623 * Valid for the following event types: 624 * o BLE_GAP_EVENT_TERM_FAILURE 625 */ 626 struct { 627 /** 628 * A BLE host return code indicating the reason for the failure. 629 */ 630 int status; 631 632 /** The handle of the relevant connection. */ 633 uint16_t conn_handle; 634 } term_failure; 635 636 /** 637 * Represents an attempt to change the encrypted state of a 638 * connection. If the attempt was successful, the connection 639 * descriptor reflects the updated encrypted state. 640 * 641 * Valid for the following event types: 642 * o BLE_GAP_EVENT_ENC_CHANGE 643 */ 644 struct { 645 /** 646 * Indicates the result of the encryption state change attempt; 647 * o 0: the encrypted state was successfully updated; 648 * o BLE host error code: the encryption state change attempt 649 * failed for the specified reason. 650 */ 651 int status; 652 653 /** The handle of the relevant connection. */ 654 uint16_t conn_handle; 655 } enc_change; 656 657 /** 658 * Represents a passkey query needed to complete a pairing procedure. 659 * 660 * Valid for the following event types: 661 * o BLE_GAP_EVENT_PASSKEY_ACTION 662 */ 663 struct { 664 /** Contains details about the passkey query. */ 665 struct ble_gap_passkey_params params; 666 667 /** The handle of the relevant connection. */ 668 uint16_t conn_handle; 669 } passkey; 670 671 /** 672 * Represents a received ATT notification or indication. 673 * 674 * Valid for the following event types: 675 * o BLE_GAP_EVENT_NOTIFY_RX 676 */ 677 struct { 678 /** 679 * The contents of the notification or indication. If the 680 * application wishes to retain this mbuf for later use, it must 681 * set this pointer to NULL to prevent the stack from freeing it. 682 */ 683 struct os_mbuf *om; 684 685 /** The handle of the relevant ATT attribute. */ 686 uint16_t attr_handle; 687 688 /** The handle of the relevant connection. */ 689 uint16_t conn_handle; 690 691 /** 692 * Whether the received command is a notification or an 693 * indication; 694 * o 0: Notification; 695 * o 1: Indication. 696 */ 697 uint8_t indication : 1; 698 } notify_rx; 699 700 /** 701 * Represents a transmitted ATT notification or indication, or a 702 * completed indication transaction. 703 * 704 * Valid for the following event types: 705 * o BLE_GAP_EVENT_NOTIFY_TX 706 */ 707 struct { 708 /** 709 * The status of the notification or indication transaction; 710 * o 0: Command successfully sent; 711 * o BLE_HS_EDONE: Confirmation (indication ack) received; 712 * o BLE_HS_ETIMEOUT: Confirmation (indication ack) never 713 * received; 714 * o Other return code: Error. 715 */ 716 int status; 717 718 /** The handle of the relevant connection. */ 719 uint16_t conn_handle; 720 721 /** The handle of the relevant characteristic value. */ 722 uint16_t attr_handle; 723 724 /** 725 * Whether the transmitted command is a notification or an 726 * indication; 727 * o 0: Notification; 728 * o 1: Indication. 729 */ 730 uint8_t indication : 1; 731 } notify_tx; 732 733 /** 734 * Represents a state change in a peer's subscription status. In this 735 * comment, the term "update" is used to refer to either a notification 736 * or an indication. This event is triggered by any of the following 737 * occurrences: 738 * o Peer enables or disables updates via a CCCD write. 739 * o Connection is about to be terminated and the peer is 740 * subscribed to updates. 741 * o Peer is now subscribed to updates after its state was restored 742 * from persistence. This happens when bonding is restored. 743 * 744 * Valid for the following event types: 745 * o BLE_GAP_EVENT_SUBSCRIBE 746 */ 747 struct { 748 /** The handle of the relevant connection. */ 749 uint16_t conn_handle; 750 751 /** The value handle of the relevant characteristic. */ 752 uint16_t attr_handle; 753 754 /** One of the BLE_GAP_SUBSCRIBE_REASON codes. */ 755 uint8_t reason; 756 757 /** Whether the peer was previously subscribed to notifications. */ 758 uint8_t prev_notify : 1; 759 760 /** Whether the peer is currently subscribed to notifications. */ 761 uint8_t cur_notify : 1; 762 763 /** Whether the peer was previously subscribed to indications. */ 764 uint8_t prev_indicate : 1; 765 766 /** Whether the peer is currently subscribed to indications. */ 767 uint8_t cur_indicate : 1; 768 } subscribe; 769 770 /** 771 * Represents a change in an L2CAP channel's MTU. 772 * 773 * Valid for the following event types: 774 * o BLE_GAP_EVENT_MTU 775 */ 776 struct { 777 /** The handle of the relevant connection. */ 778 uint16_t conn_handle; 779 780 /** 781 * Indicates the channel whose MTU has been updated; either 782 * BLE_L2CAP_CID_ATT or the ID of a connection-oriented channel. 783 */ 784 uint16_t channel_id; 785 786 /* The channel's new MTU. */ 787 uint16_t value; 788 } mtu; 789 790 /** 791 * Represents a change in peer's identity. This is issued after 792 * successful pairing when Identity Address Information was received. 793 * 794 * Valid for the following event types: 795 * o BLE_GAP_EVENT_IDENTITY_RESOLVED 796 */ 797 struct { 798 /** The handle of the relevant connection. */ 799 uint16_t conn_handle; 800 } identity_resolved; 801 802 /** 803 * Represents a peer's attempt to pair despite a bond already existing. 804 * The application has two options for handling this event type: 805 * o Retry: Return BLE_GAP_REPEAT_PAIRING_RETRY after deleting the 806 * conflicting bond. The stack will verify the bond has 807 * been deleted and continue the pairing procedure. If 808 * the bond is still present, this event will be reported 809 * again. 810 * o Ignore: Return BLE_GAP_REPEAT_PAIRING_IGNORE. The stack will 811 * silently ignore the pairing request. 812 * 813 * Valid for the following event types: 814 * o BLE_GAP_EVENT_REPEAT_PAIRING 815 */ 816 struct ble_gap_repeat_pairing repeat_pairing; 817 818 /** 819 * Represents a change of PHY. This is issue after successful 820 * change on PHY. 821 */ 822 struct { 823 int status; 824 uint16_t conn_handle; 825 826 /** 827 * Indicates enabled TX/RX PHY. Possible values: 828 * o BLE_GAP_LE_PHY_1M 829 * o BLE_GAP_LE_PHY_2M 830 * o BLE_GAP_LE_PHY_CODED 831 */ 832 uint8_t tx_phy; 833 uint8_t rx_phy; 834 } phy_updated; 835 #if MYNEWT_VAL(BLE_PERIODIC_ADV) 836 /** 837 * Represents a periodic advertising sync established during discovery 838 * procedure. Valid for the following event types: 839 * o BLE_GAP_EVENT_PERIODIC_SYNC 840 */ 841 struct { 842 /** BLE_ERR_SUCCESS on success or error code on failure. Other 843 * fields are valid only for success 844 */ 845 uint8_t status; 846 /** Periodic sync handle */ 847 uint16_t sync_handle; 848 849 /** Advertising Set ID */ 850 uint8_t sid; 851 852 /** Advertiser address */ 853 ble_addr_t adv_addr; 854 855 /** Advertising PHY, can be one of following constants: 856 * - BLE_HCI_LE_PHY_1M 857 * - LE_HCI_LE_PHY_2M 858 * - BLE_HCI_LE_PHY_CODED 859 */ 860 uint8_t adv_phy; 861 862 /** Periodic advertising interval */ 863 uint16_t per_adv_ival; 864 865 /** Advertiser clock accuracy */ 866 uint8_t adv_clk_accuracy; 867 } periodic_sync; 868 869 /** 870 * Represents a periodic advertising report received on established 871 * sync. Valid for the following event types: 872 * o BLE_GAP_EVENT_PERIODIC_REPORT 873 */ 874 struct { 875 /** Periodic sync handle */ 876 uint16_t sync_handle; 877 878 /** Advertiser transmit power in dBm (127 if unavailable) */ 879 int8_t tx_power; 880 881 /** Received signal strength indication in dBm (127 if unavailable) */ 882 int8_t rssi; 883 884 /** Advertising data status, can be one of following constants: 885 * - BLE_HCI_PERIODIC_DATA_STATUS_COMPLETE 886 * - BLE_HCI_PERIODIC_DATA_STATUS_INCOMPLETE 887 * - BLE_HCI_PERIODIC_DATA_STATUS_TRUNCATED 888 */ 889 uint8_t data_status; 890 891 /** Advertising Data length */ 892 uint8_t data_length; 893 894 /** Advertising data */ 895 const uint8_t *data; 896 } periodic_report; 897 898 /** 899 * Represents a periodic advertising sync lost of established sync. 900 * Sync lost reason can be BLE_HS_ETIMEOUT (sync timeout) or 901 * BLE_HS_EDONE (sync terminated locally). 902 * Valid for the following event types: 903 * o BLE_GAP_EVENT_PERIODIC_SYNC_LOST 904 */ 905 struct { 906 /** Periodic sync handle */ 907 uint16_t sync_handle; 908 909 /** Reason for sync lost, can be BLE_HS_ETIMEOUT for timeout or 910 * BLE_HS_EDONE for locally terminated sync 911 */ 912 int reason; 913 } periodic_sync_lost; 914 #endif 915 916 #if MYNEWT_VAL(BLE_EXT_ADV) 917 /** 918 * Represents a scan request for an extended advertising instance where 919 * scan request notifications were enabled. 920 * Valid for the following event types: 921 * o BLE_GAP_EVENT_SCAN_REQ_RCVD 922 */ 923 struct { 924 /** Extended advertising instance */ 925 uint8_t instance; 926 /** Address of scanner */ 927 ble_addr_t scan_addr; 928 } scan_req_rcvd; 929 #endif 930 #if MYNEWT_VAL(BLE_PERIODIC_ADV_SYNC_TRANSFER) 931 /** 932 * Represents a periodic advertising sync transfer received. Valid for 933 * the following event types: 934 * o BLE_GAP_EVENT_PERIODIC_TRANSFER 935 */ 936 struct { 937 /** BLE_ERR_SUCCESS on success or error code on failure. Sync handle 938 * is valid only for success. 939 */ 940 uint8_t status; 941 942 /** Periodic sync handle */ 943 uint16_t sync_handle; 944 945 /** Connection handle */ 946 uint16_t conn_handle; 947 948 /** Service Data */ 949 uint16_t service_data; 950 951 /** Advertising Set ID */ 952 uint8_t sid; 953 954 /** Advertiser address */ 955 ble_addr_t adv_addr; 956 957 /** Advertising PHY, can be one of following constants: 958 * - BLE_HCI_LE_PHY_1M 959 * - LE_HCI_LE_PHY_2M 960 * - BLE_HCI_LE_PHY_CODED 961 */ 962 uint8_t adv_phy; 963 964 /** Periodic advertising interval */ 965 uint16_t per_adv_itvl; 966 967 /** Advertiser clock accuracy */ 968 uint8_t adv_clk_accuracy; 969 } periodic_transfer; 970 #endif 971 }; 972 }; 973 974 typedef int ble_gap_event_fn(struct ble_gap_event *event, void *arg); 975 976 #define BLE_GAP_CONN_MODE_NON 0 977 #define BLE_GAP_CONN_MODE_DIR 1 978 #define BLE_GAP_CONN_MODE_UND 2 979 980 #define BLE_GAP_DISC_MODE_NON 0 981 #define BLE_GAP_DISC_MODE_LTD 1 982 #define BLE_GAP_DISC_MODE_GEN 2 983 984 /** 985 * Searches for a connection with the specified handle. If a matching 986 * connection is found, the supplied connection descriptor is filled 987 * correspondingly. 988 * 989 * @param handle The connection handle to search for. 990 * @param out_desc On success, this is populated with information relating to 991 * the matching connection. Pass NULL if you don't need this 992 * information. 993 * 994 * @return 0 on success, BLE_HS_ENOTCONN if no matching connection was 995 * found. 996 */ 997 int ble_gap_conn_find(uint16_t handle, struct ble_gap_conn_desc *out_desc); 998 999 /** 1000 * Searches for a connection with a peer with the specified address. 1001 * If a matching connection is found, the supplied connection descriptor 1002 * is filled correspondingly. 1003 * 1004 * @param addr The ble address of a connected peer device to search for. 1005 * @param out_desc On success, this is populated with information relating to 1006 * the matching connection. Pass NULL if you don't need this 1007 * information. 1008 * 1009 * @return 0 on success, BLE_HS_ENOTCONN if no matching connection was 1010 * found. 1011 */ 1012 int ble_gap_conn_find_by_addr(const ble_addr_t *addr, 1013 struct ble_gap_conn_desc *out_desc); 1014 1015 /** 1016 * Configures a connection to use the specified GAP event callback. A 1017 * connection's GAP event callback is first specified when the connection is 1018 * created, either via advertising or initiation. This function replaces the 1019 * callback that was last configured. 1020 * 1021 * @param conn_handle The handle of the connection to configure. 1022 * @param cb The callback to associate with the connection. 1023 * @param cb_arg An optional argument that the callback receives. 1024 * 1025 * @return 0 on success, BLE_HS_ENOTCONN if there is no connection 1026 * with the specified handle. 1027 */ 1028 int ble_gap_set_event_cb(uint16_t conn_handle, 1029 ble_gap_event_fn *cb, void *cb_arg); 1030 1031 /** @brief Start advertising 1032 * 1033 * This function configures and start advertising procedure. 1034 * 1035 * @param own_addr_type The type of address the stack should use for itself. 1036 * Valid values are: 1037 * - BLE_OWN_ADDR_PUBLIC 1038 * - BLE_OWN_ADDR_RANDOM 1039 * - BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT 1040 * - BLE_OWN_ADDR_RPA_RANDOM_DEFAULT 1041 * @param direct_addr The peer's address for directed advertising. This 1042 * parameter shall be non-NULL if directed advertising is 1043 * being used. 1044 * @param duration_ms The duration of the advertisement procedure. On 1045 * expiration, the procedure ends and a 1046 * BLE_GAP_EVENT_ADV_COMPLETE event is reported. Units are 1047 * milliseconds. Specify BLE_HS_FOREVER for no expiration. 1048 * @param adv_params Additional arguments specifying the particulars of the 1049 * advertising procedure. 1050 * @param cb The callback to associate with this advertising 1051 * procedure. If advertising ends, the event is reported 1052 * through this callback. If advertising results in a 1053 * connection, the connection inherits this callback as its 1054 * event-reporting mechanism. 1055 * @param cb_arg The optional argument to pass to the callback function. 1056 * 1057 * @return 0 on success, error code on failure. 1058 */ 1059 int ble_gap_adv_start(uint8_t own_addr_type, const ble_addr_t *direct_addr, 1060 int32_t duration_ms, 1061 const struct ble_gap_adv_params *adv_params, 1062 ble_gap_event_fn *cb, void *cb_arg); 1063 1064 /** 1065 * Stops the currently-active advertising procedure. A success return 1066 * code indicates that advertising has been fully aborted and a new advertising 1067 * procedure can be initiated immediately. 1068 * 1069 * NOTE: If the caller is running in the same task as the NimBLE host, or if it 1070 * is running in a higher priority task than that of the host, care must be 1071 * taken when restarting advertising. Under these conditions, the following is 1072 * *not* a reliable method to restart advertising: 1073 * ble_gap_adv_stop() 1074 * ble_gap_adv_start() 1075 * 1076 * Instead, the call to `ble_gap_adv_start()` must be made in a separate event 1077 * context. That is, `ble_gap_adv_start()` must be called asynchronously by 1078 * enqueueing an event on the current task's event queue. See 1079 * https://github.com/apache/mynewt-nimble/pull/211 for more information. 1080 * 1081 * @return 0 on success, BLE_HS_EALREADY if there is no active advertising 1082 * procedure, other error code on failure. 1083 */ 1084 int ble_gap_adv_stop(void); 1085 1086 /** 1087 * Indicates whether an advertisement procedure is currently in progress. 1088 * 1089 * @return 0 if no advertisement procedure in progress, 1 otherwise. 1090 */ 1091 int ble_gap_adv_active(void); 1092 1093 /** 1094 * Configures the data to include in subsequent advertisements. 1095 * 1096 * @param data Buffer containing the advertising data. 1097 * @param data_len The size of the advertising data, in bytes. 1098 * 1099 * @return 0 on succes, BLE_HS_EBUSY if advertising is in progress, 1100 * other error code on failure. 1101 */ 1102 int ble_gap_adv_set_data(const uint8_t *data, int data_len); 1103 1104 /** 1105 * Configures the data to include in subsequent scan responses. 1106 * 1107 * @param data Buffer containing the scan response data. 1108 * @param data_len The size of the response data, in bytes. 1109 * 1110 * @return 0 on succes, BLE_HS_EBUSY if advertising is in progress, 1111 * other error code on failure. 1112 */ 1113 int ble_gap_adv_rsp_set_data(const uint8_t *data, int data_len); 1114 1115 /** 1116 * Configures the fields to include in subsequent advertisements. This is a 1117 * convenience wrapper for ble_gap_adv_set_data(). 1118 * 1119 * @param adv_fields Specifies the advertisement data. 1120 * 1121 * @return 0 on success, 1122 * BLE_HS_EBUSY if advertising is in progress, 1123 * BLE_HS_EMSGSIZE if the specified data is too large to 1124 * fit in an advertisement, 1125 * other error code on failure. 1126 */ 1127 int ble_gap_adv_set_fields(const struct ble_hs_adv_fields *rsp_fields); 1128 1129 /** 1130 * Configures the fields to include in subsequent scan responses. This is a 1131 * convenience wrapper for ble_gap_adv_rsp_set_data(). 1132 * 1133 * @param adv_fields Specifies the scan response data. 1134 * 1135 * @return 0 on success, 1136 * BLE_HS_EBUSY if advertising is in progress, 1137 * BLE_HS_EMSGSIZE if the specified data is too large to 1138 * fit in a scan response, 1139 * other error code on failure. 1140 */ 1141 int ble_gap_adv_rsp_set_fields(const struct ble_hs_adv_fields *rsp_fields); 1142 1143 #if MYNEWT_VAL(BLE_EXT_ADV) 1144 /** @brief Extended advertising parameters */ 1145 struct ble_gap_ext_adv_params { 1146 /** If perform connectable advertising */ 1147 unsigned int connectable : 1; 1148 1149 /** If perform scannable advertising */ 1150 unsigned int scannable : 1; 1151 1152 /** If perform directed advertising */ 1153 unsigned int directed : 1; 1154 1155 /** If perform high-duty directed advertising */ 1156 unsigned int high_duty_directed : 1; 1157 1158 /** If use legacy PDUs for advertising */ 1159 unsigned int legacy_pdu : 1; 1160 1161 /** If perform anonymous advertising */ 1162 unsigned int anonymous : 1; 1163 1164 /** If include TX power in advertising PDU */ 1165 unsigned int include_tx_power : 1; 1166 1167 /** If enable scan request notification */ 1168 unsigned int scan_req_notif : 1; 1169 1170 /** Minimum advertising interval in 0.625ms units, if 0 stack use sane 1171 * defaults 1172 */ 1173 uint32_t itvl_min; 1174 1175 /** Maximum advertising interval in 0.625ms units, if 0 stack use sane 1176 * defaults 1177 */ 1178 uint32_t itvl_max; 1179 1180 /** Advertising channel map , if 0 stack use sane defaults */ 1181 uint8_t channel_map; 1182 1183 /** Own address type to be used by advertising instance */ 1184 uint8_t own_addr_type; 1185 1186 /** Peer address for directed advertising, valid only if directed is set */ 1187 ble_addr_t peer; 1188 1189 /** Advertising Filter policy */ 1190 uint8_t filter_policy; 1191 1192 /** Primary advertising PHY to use , can be one of following constants: 1193 * - BLE_HCI_LE_PHY_1M 1194 * - BLE_HCI_LE_PHY_CODED 1195 */ 1196 uint8_t primary_phy; 1197 1198 /** Secondary advertising PHY to use, can be one of following constants: 1199 * - BLE_HCI_LE_PHY_1M 1200 * - LE_HCI_LE_PHY_2M 1201 * - BLE_HCI_LE_PHY_CODED 1202 */ 1203 uint8_t secondary_phy; 1204 1205 /** Preferred advertiser transmit power */ 1206 int8_t tx_power; 1207 1208 /** Advertising Set ID */ 1209 uint8_t sid; 1210 }; 1211 1212 /** 1213 * Configure extended advertising instance 1214 * 1215 * @param instance Instance ID 1216 * @param params Additional arguments specifying the particulars 1217 * of the advertising. 1218 * @param selected_tx_power Selected advertising transmit power will be 1219 * stored in that param if non-NULL. 1220 * @param cb The callback to associate with this advertising 1221 * procedure. Advertising complete event is reported 1222 * through this callback 1223 * @param cb_arg The optional argument to pass to the callback 1224 * function. 1225 * 1226 * @return 0 on success; nonzero on failure. 1227 */ 1228 int ble_gap_ext_adv_configure(uint8_t instance, 1229 const struct ble_gap_ext_adv_params *params, 1230 int8_t *selected_tx_power, 1231 ble_gap_event_fn *cb, void *cb_arg); 1232 1233 /** 1234 * Set random address for configured advertising instance. 1235 * 1236 * @param instance Instance ID 1237 * @param addr Random address to be set 1238 * 1239 * @return 0 on success; nonzero on failure. 1240 */ 1241 int ble_gap_ext_adv_set_addr(uint8_t instance, const ble_addr_t *addr); 1242 1243 /** 1244 * Start advertising instance. 1245 * 1246 * @param instance Instance ID 1247 * @param duration The duration of the advertisement procedure. On 1248 * expiration, the procedure ends and 1249 * a BLE_GAP_EVENT_ADV_COMPLETE event is reported. 1250 * Units are 10 milliseconds. Specify 0 for no 1251 * expiration. 1252 * @params max_events Number of advertising events that should be sent 1253 * before advertising ends and 1254 * a BLE_GAP_EVENT_ADV_COMPLETE event is reported. 1255 * Specify 0 for no limit. 1256 * 1257 * @return 0 on success, error code on failure. 1258 */ 1259 int ble_gap_ext_adv_start(uint8_t instance, int duration, int max_events); 1260 1261 /** 1262 * Stops advertising procedure for specified instance. 1263 * 1264 * @param instance Instance ID 1265 * 1266 * @return 0 on success, BLE_HS_EALREADY if there is no active advertising 1267 * procedure for instance, other error code on failure. 1268 */ 1269 int ble_gap_ext_adv_stop(uint8_t instance); 1270 1271 /** 1272 * Configures the data to include in advertisements packets for specified 1273 * advertising instance. 1274 * 1275 * @param instance Instance ID 1276 * @param data Chain containing the advertising data. 1277 * 1278 * @return 0 on success or error code on failure. 1279 */ 1280 int ble_gap_ext_adv_set_data(uint8_t instance, struct os_mbuf *data); 1281 1282 /** 1283 * Configures the data to include in subsequent scan responses for specified 1284 * advertisign instance. 1285 * 1286 * @param instance Instance ID 1287 * @param data Chain containing the scan response data. 1288 * 1289 * @return 0 on success or error code on failure. 1290 */ 1291 1292 int ble_gap_ext_adv_rsp_set_data(uint8_t instance, struct os_mbuf *data); 1293 1294 /** 1295 * Remove existing advertising instance. 1296 * 1297 * @param instance Instance ID 1298 * 1299 * @return 0 on success, 1300 * BLE_HS_EBUSY if advertising is in progress, 1301 * other error code on failure. 1302 */ 1303 int ble_gap_ext_adv_remove(uint8_t instance); 1304 1305 /** 1306 * Clear all existing advertising instances 1307 * @return 0 on success, 1308 * BLE_HS_EBUSY if advertising is in progress, 1309 * other error code on failure. 1310 */ 1311 int ble_gap_ext_adv_clear(void); 1312 #endif 1313 1314 /* Periodic Advertising */ 1315 #if MYNEWT_VAL(BLE_PERIODIC_ADV) 1316 1317 /** @brief Periodic advertising parameters */ 1318 struct ble_gap_periodic_adv_params { 1319 /** If include TX power in advertising PDU */ 1320 unsigned int include_tx_power : 1; 1321 1322 /** Minimum advertising interval in 0.625ms units, if 0 stack use sane 1323 * defaults 1324 */ 1325 uint16_t itvl_min; 1326 1327 /** Maximum advertising interval in 0.625ms units, if 0 stack use sane 1328 * defaults 1329 */ 1330 uint16_t itvl_max; 1331 }; 1332 1333 /** @brief Periodic sync parameters */ 1334 struct ble_gap_periodic_sync_params { 1335 /** The maximum number of periodic advertising events that controller can 1336 * skip after a successful receive. 1337 * */ 1338 uint16_t skip; 1339 1340 /** Synchronization timeout for the periodic advertising train in 10ms units 1341 */ 1342 uint16_t sync_timeout; 1343 1344 /** If reports should be initially disabled when sync is created */ 1345 unsigned int reports_disabled : 1; 1346 }; 1347 1348 /** 1349 * Configure periodic advertising for specified advertising instance 1350 * 1351 * This is allowed only for instances configured as non-announymous, 1352 * non-connectable and non-scannable. 1353 * 1354 * @param instance Instance ID 1355 * @param params Additional arguments specifying the particulars 1356 * of periodic advertising. 1357 * 1358 * @return 0 on success; nonzero on failure. 1359 */ 1360 int ble_gap_periodic_adv_configure(uint8_t instance, 1361 const struct ble_gap_periodic_adv_params *params); 1362 1363 /** 1364 * Start periodic advertising for specified advertising instance. 1365 * 1366 * @param instance Instance ID 1367 * 1368 * @return 0 on success, error code on failure. 1369 */ 1370 int ble_gap_periodic_adv_start(uint8_t instance); 1371 1372 /** 1373 * Stop periodic advertising for specified advertising instance. 1374 * 1375 * @param instance Instance ID 1376 * 1377 * @return 0 on success, error code on failure. 1378 */ 1379 int ble_gap_periodic_adv_stop(uint8_t instance); 1380 1381 /** 1382 * Configures the data to include in periodic advertisements for specified 1383 * advertising instance. 1384 * 1385 * @param instance Instance ID 1386 * @param data Chain containing the periodic advertising data. 1387 * 1388 * @return 0 on success or error code on failure. 1389 */ 1390 int ble_gap_periodic_adv_set_data(uint8_t instance, struct os_mbuf *data); 1391 1392 /** 1393 * Performs the Synchronization procedure with periodic advertiser. 1394 * 1395 * @param addr Peer address to synchronize with. If NULL than 1396 * peers from periodic list are used. 1397 * @param adv_sid Advertiser Set ID 1398 * @param params Additional arguments specifying the particulars 1399 * of the synchronization procedure. 1400 * @param cb The callback to associate with this synchrnization 1401 * procedure. BLE_GAP_EVENT_PERIODIC_REPORT events 1402 * are reported only by this callback. 1403 * @param cb_arg The optional argument to pass to the callback 1404 * function. 1405 * 1406 * @return 0 on success; nonzero on failure. 1407 */ 1408 int ble_gap_periodic_adv_sync_create(const ble_addr_t *addr, uint8_t adv_sid, 1409 const struct ble_gap_periodic_sync_params *params, 1410 ble_gap_event_fn *cb, void *cb_arg); 1411 1412 /** 1413 * Cancel pending synchronization procedure. 1414 * 1415 * @return 0 on success; nonzero on failure. 1416 */ 1417 int ble_gap_periodic_adv_sync_create_cancel(void); 1418 1419 /** 1420 * Terminate synchronization procedure. 1421 * 1422 * @param sync_handle Handle identifying synchronization to terminate. 1423 * 1424 * @return 0 on success; nonzero on failure. 1425 */ 1426 int ble_gap_periodic_adv_sync_terminate(uint16_t sync_handle); 1427 1428 #if MYNEWT_VAL(BLE_PERIODIC_ADV_SYNC_TRANSFER) 1429 /** 1430 * Disable or enable periodic reports for specified sync. 1431 * 1432 * @param sync_handle Handle identifying synchronization. 1433 * @param enable If reports should be enabled. 1434 * 1435 * @return 0 on success; nonzero on failure. 1436 */ 1437 int ble_gap_periodic_adv_sync_reporting(uint16_t sync_handle, bool enable); 1438 1439 /** 1440 * Initialize sync transfer procedure for specified handles. 1441 * 1442 * This allows to transfer periodic sync to which host is synchronized. 1443 * 1444 * @param sync_handle Handle identifying synchronization. 1445 * @param conn_handle Handle identifying connection. 1446 * @param service_data Sync transfer service data 1447 * 1448 * @return 0 on success; nonzero on failure. 1449 */ 1450 int ble_gap_periodic_adv_sync_transfer(uint16_t sync_handle, 1451 uint16_t conn_handle, 1452 uint16_t service_data); 1453 1454 /** 1455 * Initialize set info transfer procedure for specified handles. 1456 * 1457 * This allows to transfer periodic sync which is being advertised by host. 1458 * 1459 * @param instance Advertising instance with periodic adv enabled. 1460 * @param conn_handle Handle identifying connection. 1461 * @param service_data Sync transfer service data 1462 * 1463 * @return 0 on success; nonzero on failure. 1464 */ 1465 int ble_gap_periodic_adv_sync_set_info(uint8_t instance, 1466 uint16_t conn_handle, 1467 uint16_t service_data); 1468 1469 /** 1470 * Enables or disables sync transfer reception on specified connection. 1471 * When sync transfer arrives, BLE_GAP_EVENT_PERIODIC_TRANSFER is sent to the user. 1472 * After that, sync transfer reception on that connection is terminated and user needs 1473 * to call this API again when expect to receive next sync transfers. 1474 * 1475 * Note: If ACL connection gets disconnected before sync transfer arrived, user will 1476 * not receive BLE_GAP_EVENT_PERIODIC_TRANSFER. Instead, sync transfer reception 1477 * is terminated by the host automatically. 1478 * 1479 * @param conn_handle Handle identifying connection. 1480 * @param params Parameters for enabled sync transfer reception. 1481 * Specify NULL to disable reception. 1482 * @param cb The callback to associate with this synchronization 1483 * procedure. BLE_GAP_EVENT_PERIODIC_REPORT events 1484 * are reported only by this callback. 1485 * @param cb_arg The optional argument to pass to the callback 1486 * function. 1487 * 1488 * @return 0 on success; nonzero on failure. 1489 */ 1490 int ble_gap_periodic_adv_sync_receive(uint16_t conn_handle, 1491 const struct ble_gap_periodic_sync_params *params, 1492 ble_gap_event_fn *cb, void *cb_arg); 1493 #endif 1494 1495 /** 1496 * Add peer device to periodic synchronization list. 1497 * 1498 * @param addr Peer address to add to list. 1499 * @param adv_sid Advertiser Set ID 1500 * 1501 * @return 0 on success; nonzero on failure. 1502 */ 1503 int ble_gap_add_dev_to_periodic_adv_list(const ble_addr_t *peer_addr, uint8_t adv_sid); 1504 1505 /** 1506 * Remove peer device from periodic synchronization list. 1507 * 1508 * @param addr Peer address to remove from list. 1509 * @param adv_sid Advertiser Set ID 1510 * 1511 * @return 0 on success; nonzero on failure. 1512 */ 1513 int ble_gap_rem_dev_from_periodic_adv_list(const ble_addr_t *peer_addr, uint8_t adv_sid); 1514 1515 /** 1516 * Clear periodic synchrnization list. 1517 * 1518 * @return 0 on success; nonzero on failure. 1519 */ 1520 int ble_gap_clear_periodic_adv_list(void); 1521 1522 /** 1523 * Get periodic synchronization list size. 1524 * 1525 * @param per_adv_list_size On success list size is stored here. 1526 * 1527 * @return 0 on success; nonzero on failure. 1528 */ 1529 int ble_gap_read_periodic_adv_list_size(uint8_t *per_adv_list_size); 1530 #endif 1531 1532 /** 1533 * Performs the Limited or General Discovery Procedures. 1534 * 1535 * @param own_addr_type The type of address the stack should use for 1536 * itself when sending scan requests. Valid 1537 * values are: 1538 * - BLE_ADDR_TYPE_PUBLIC 1539 * - BLE_ADDR_TYPE_RANDOM 1540 * - BLE_ADDR_TYPE_RPA_PUB_DEFAULT 1541 * - BLE_ADDR_TYPE_RPA_RND_DEFAULT 1542 * This parameter is ignored unless active 1543 * scanning is being used. 1544 * @param duration_ms The duration of the discovery procedure. 1545 * On expiration, the procedure ends and a 1546 * BLE_GAP_EVENT_DISC_COMPLETE event is 1547 * reported. Units are milliseconds. Specify 1548 * BLE_HS_FOREVER for no expiration. Specify 1549 * 0 to use stack defaults. 1550 * @param disc_params Additional arguments specifying the particulars 1551 * of the discovery procedure. 1552 * @param cb The callback to associate with this discovery 1553 * procedure. Advertising reports and 1554 * discovery termination events are reported 1555 * through this callback. 1556 * @param cb_arg The optional argument to pass to the callback 1557 * function. 1558 * 1559 * @return 0 on success; nonzero on failure. 1560 */ 1561 int ble_gap_disc(uint8_t own_addr_type, int32_t duration_ms, 1562 const struct ble_gap_disc_params *disc_params, 1563 ble_gap_event_fn *cb, void *cb_arg); 1564 1565 /** 1566 * Performs the Limited or General Extended Discovery Procedures. 1567 * 1568 * @param own_addr_type The type of address the stack should use for 1569 * itself when sending scan requests. Valid 1570 * values are: 1571 * - BLE_ADDR_TYPE_PUBLIC 1572 * - BLE_ADDR_TYPE_RANDOM 1573 * - BLE_ADDR_TYPE_RPA_PUB_DEFAULT 1574 * - BLE_ADDR_TYPE_RPA_RND_DEFAULT 1575 * This parameter is ignored unless active 1576 * scanning is being used. 1577 * @param duration The duration of the discovery procedure. 1578 * On expiration, if period is set to 0, the 1579 * procedure ends and a 1580 * BLE_GAP_EVENT_DISC_COMPLETE event is 1581 * reported. Units are 10 milliseconds. 1582 * Specify 0 for no expiration. 1583 * @param period Time interval from when the Controller started 1584 * its last Scan Duration until it begins the 1585 * subsequent Scan Duration. Specify 0 to scan 1586 * continuously. Units are 1.28 second. 1587 * @param limited If limited discovery procedure should be used. 1588 * @param uncoded_params Additional arguments specifying the particulars 1589 * of the discovery procedure for uncoded PHY. 1590 * If NULL is provided no scan is performed for 1591 * this PHY. 1592 * @param coded_params Additional arguments specifying the particulars 1593 * of the discovery procedure for coded PHY. 1594 * If NULL is provided no scan is performed for 1595 * this PHY. 1596 * @param cb The callback to associate with this discovery 1597 * procedure. Advertising reports and discovery 1598 * termination events are reported through this 1599 * callback. 1600 * @param cb_arg The optional argument to pass to the callback 1601 * function. 1602 * 1603 * @return 0 on success; nonzero on failure. 1604 */ 1605 int ble_gap_ext_disc(uint8_t own_addr_type, uint16_t duration, uint16_t period, 1606 uint8_t filter_duplicates, uint8_t filter_policy, 1607 uint8_t limited, 1608 const struct ble_gap_ext_disc_params *uncoded_params, 1609 const struct ble_gap_ext_disc_params *coded_params, 1610 ble_gap_event_fn *cb, void *cb_arg); 1611 1612 /** 1613 * Cancels the discovery procedure currently in progress. A success return 1614 * code indicates that scanning has been fully aborted; a new discovery or 1615 * connect procedure can be initiated immediately. 1616 * 1617 * @return 0 on success; 1618 * BLE_HS_EALREADY if there is no discovery 1619 * procedure to cancel; 1620 * Other nonzero on unexpected error. 1621 */ 1622 int ble_gap_disc_cancel(void); 1623 1624 /** 1625 * Indicates whether a discovery procedure is currently in progress. 1626 * 1627 * @return 0: No discovery procedure in progress; 1628 * 1: Discovery procedure in progress. 1629 */ 1630 int ble_gap_disc_active(void); 1631 1632 /** 1633 * Initiates a connect procedure. 1634 * 1635 * @param own_addr_type The type of address the stack should use for 1636 * itself during connection establishment. 1637 * - BLE_OWN_ADDR_PUBLIC 1638 * - BLE_OWN_ADDR_RANDOM 1639 * - BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT 1640 * - BLE_OWN_ADDR_RPA_RANDOM_DEFAULT 1641 * @param peer_addr The address of the peer to connect to. 1642 * If this parameter is NULL, the white list 1643 * is used. 1644 * @param duration_ms The duration of the discovery procedure. 1645 * On expiration, the procedure ends and a 1646 * BLE_GAP_EVENT_DISC_COMPLETE event is 1647 * reported. Units are milliseconds. 1648 * @param conn_params Additional arguments specifying the particulars 1649 * of the connect procedure. Specify null for 1650 * default values. 1651 * @param cb The callback to associate with this connect 1652 * procedure. When the connect procedure 1653 * completes, the result is reported through 1654 * this callback. If the connect procedure 1655 * succeeds, the connection inherits this 1656 * callback as its event-reporting mechanism. 1657 * @param cb_arg The optional argument to pass to the callback 1658 * function. 1659 * 1660 * @return 0 on success; 1661 * BLE_HS_EALREADY if a connection attempt is 1662 * already in progress; 1663 * BLE_HS_EBUSY if initiating a connection is not 1664 * possible because scanning is in progress; 1665 * BLE_HS_EDONE if the specified peer is already 1666 * connected; 1667 * Other nonzero on error. 1668 */ 1669 int ble_gap_connect(uint8_t own_addr_type, const ble_addr_t *peer_addr, 1670 int32_t duration_ms, 1671 const struct ble_gap_conn_params *params, 1672 ble_gap_event_fn *cb, void *cb_arg); 1673 1674 /** 1675 * Initiates an extended connect procedure. 1676 * 1677 * @param own_addr_type The type of address the stack should use for 1678 * itself during connection establishment. 1679 * - BLE_OWN_ADDR_PUBLIC 1680 * - BLE_OWN_ADDR_RANDOM 1681 * - BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT 1682 * - BLE_OWN_ADDR_RPA_RANDOM_DEFAULT 1683 * @param peer_addr The address of the peer to connect to. 1684 * If this parameter is NULL, the white list 1685 * is used. 1686 * @param duration_ms The duration of the discovery procedure. 1687 * On expiration, the procedure ends and a 1688 * BLE_GAP_EVENT_DISC_COMPLETE event is 1689 * reported. Units are milliseconds. 1690 * @param phy_mask Define on which PHYs connection attempt should 1691 * be done 1692 * @param phy_1m_conn_params Additional arguments specifying the 1693 * particulars of the connect procedure. When 1694 * BLE_GAP_LE_PHY_1M_MASK is set in phy_mask 1695 * this parameter can be specify to null for 1696 * default values. 1697 * @param phy_2m_conn_params Additional arguments specifying the 1698 * particulars of the connect procedure. When 1699 * BLE_GAP_LE_PHY_2M_MASK is set in phy_mask 1700 * this parameter can be specify to null for 1701 * default values. 1702 * @param phy_coded_conn_params Additional arguments specifying the 1703 * particulars of the connect procedure. When 1704 * BLE_GAP_LE_PHY_CODED_MASK is set in 1705 * phy_mask this parameter can be specify to 1706 * null for default values. 1707 * @param cb The callback to associate with this connect 1708 * procedure. When the connect procedure 1709 * completes, the result is reported through 1710 * this callback. If the connect procedure 1711 * succeeds, the connection inherits this 1712 * callback as its event-reporting mechanism. 1713 * @param cb_arg The optional argument to pass to the callback 1714 * function. 1715 * 1716 * @return 0 on success; 1717 * BLE_HS_EALREADY if a connection attempt is 1718 * already in progress; 1719 * BLE_HS_EBUSY if initiating a connection is not 1720 * possible because scanning is in progress; 1721 * BLE_HS_EDONE if the specified peer is already 1722 * connected; 1723 * Other nonzero on error. 1724 */ 1725 int ble_gap_ext_connect(uint8_t own_addr_type, const ble_addr_t *peer_addr, 1726 int32_t duration_ms, uint8_t phy_mask, 1727 const struct ble_gap_conn_params *phy_1m_conn_params, 1728 const struct ble_gap_conn_params *phy_2m_conn_params, 1729 const struct ble_gap_conn_params *phy_coded_conn_params, 1730 ble_gap_event_fn *cb, void *cb_arg); 1731 1732 /** 1733 * Aborts a connect procedure in progress. 1734 * 1735 * @return 0 on success; 1736 * BLE_HS_EALREADY if there is no active connect 1737 * procedure. 1738 * Other nonzero on error. 1739 */ 1740 int ble_gap_conn_cancel(void); 1741 1742 /** 1743 * Indicates whether a connect procedure is currently in progress. 1744 * 1745 * @return 0: No connect procedure in progress; 1746 * 1: Connect procedure in progress. 1747 */ 1748 int ble_gap_conn_active(void); 1749 1750 /** 1751 * Terminates an established connection. 1752 * 1753 * @param conn_handle The handle corresponding to the connection to 1754 * terminate. 1755 * @param hci_reason The HCI error code to indicate as the reason 1756 * for termination. 1757 * 1758 * @return 0 on success; 1759 * BLE_HS_ENOTCONN if there is no connection with 1760 * the specified handle; 1761 * Other nonzero on failure. 1762 */ 1763 int ble_gap_terminate(uint16_t conn_handle, uint8_t hci_reason); 1764 int ble_gap_set_data_length(uint16_t conn_handle, uint16_t tx_octets, uint16_t tx_time); 1765 1766 /** 1767 * Overwrites the controller's white list with the specified contents. 1768 * 1769 * @param addrs The entries to write to the white list. 1770 * @param white_list_count The number of entries in the white list. 1771 * 1772 * @return 0 on success; nonzero on failure. 1773 */ 1774 int ble_gap_wl_set(const ble_addr_t *addrs, uint8_t white_list_count); 1775 1776 /** 1777 * Initiates a connection parameter update procedure. 1778 * 1779 * @param conn_handle The handle corresponding to the connection to 1780 * update. 1781 * @param params The connection parameters to attempt to update 1782 * to. 1783 * 1784 * @return 0 on success; 1785 * BLE_HS_ENOTCONN if the there is no connection 1786 * with the specified handle; 1787 * BLE_HS_EALREADY if a connection update 1788 * procedure for this connection is already in 1789 * progress; 1790 * BLE_HS_EINVAL if requested parameters are 1791 * invalid; 1792 * Other nonzero on error. 1793 */ 1794 int ble_gap_update_params(uint16_t conn_handle, 1795 const struct ble_gap_upd_params *params); 1796 1797 /** 1798 * Initiates the GAP security procedure. 1799 * 1800 * Depending on connection role and stored security information this function 1801 * will start appropriate security procedure (pairing or encryption). 1802 * 1803 * @param conn_handle The handle corresponding to the connection to 1804 * secure. 1805 * 1806 * @return 0 on success; 1807 * BLE_HS_ENOTCONN if the there is no connection 1808 * with the specified handle; 1809 * BLE_HS_EALREADY if an security procedure for 1810 * this connection is already in progress; 1811 * Other nonzero on error. 1812 */ 1813 int ble_gap_security_initiate(uint16_t conn_handle); 1814 1815 /** 1816 * Initiates the GAP pairing procedure as a master. This is for testing only and 1817 * should not be used by application. Use ble_gap_security_initiate() instead. 1818 * 1819 * @param conn_handle The handle corresponding to the connection to 1820 * start pairing on. 1821 * 1822 * @return 0 on success; 1823 * BLE_HS_ENOTCONN if the there is no connection 1824 * with the specified handle; 1825 * BLE_HS_EALREADY if an pairing procedure for 1826 * this connection is already in progress; 1827 * Other nonzero on error. 1828 */ 1829 int ble_gap_pair_initiate(uint16_t conn_handle); 1830 1831 /** 1832 * Initiates the GAP encryption procedure as a master. This is for testing only 1833 * and should not be used by application. Use ble_gap_security_initiate() 1834 * instead. 1835 * 1836 * @param conn_handle The handle corresponding to the connection to 1837 * start encryption. 1838 * @param key_size Encryption key size 1839 * @param ltk Long Term Key to be used for encryption. 1840 * @param udiv Encryption Diversifier for LTK 1841 * @param rand_val Random Value for EDIV and LTK 1842 * @param auth If LTK provided is authenticated. 1843 * 1844 * @return 0 on success; 1845 * BLE_HS_ENOTCONN if the there is no connection 1846 * with the specified handle; 1847 * BLE_HS_EALREADY if an encryption procedure for 1848 * this connection is already in progress; 1849 * Other nonzero on error. 1850 */ 1851 int ble_gap_encryption_initiate(uint16_t conn_handle, uint8_t key_size, 1852 const uint8_t *ltk, uint16_t ediv, 1853 uint64_t rand_val, int auth); 1854 1855 /** 1856 * Retrieves the most-recently measured RSSI for the specified connection. A 1857 * connection's RSSI is updated whenever a data channel PDU is received. 1858 * 1859 * @param conn_handle Specifies the connection to query. 1860 * @param out_rssi On success, the retrieved RSSI is written here. 1861 * 1862 * @return 0 on success; 1863 * A BLE host HCI return code if the controller 1864 * rejected the request; 1865 * A BLE host core return code on unexpected 1866 * error. 1867 */ 1868 int ble_gap_conn_rssi(uint16_t conn_handle, int8_t *out_rssi); 1869 1870 /** 1871 * Unpairs a device with the specified address. The keys related to that peer 1872 * device are removed from storage and peer address is removed from the resolve 1873 * list from the controller. If a peer is connected, the connection is terminated. 1874 * 1875 * @param peer_addr Address of the device to be unpaired 1876 * 1877 * @return 0 on success; 1878 * A BLE host HCI return code if the controller 1879 * rejected the request; 1880 * A BLE host core return code on unexpected 1881 * error. 1882 */ 1883 int ble_gap_unpair(const ble_addr_t *peer_addr); 1884 1885 /** 1886 * Unpairs the oldest bonded peer device. The keys related to that peer 1887 * device are removed from storage and peer address is removed from the resolve 1888 * list from the controller. If a peer is connected, the connection is terminated. 1889 * 1890 * @return 0 on success; 1891 * A BLE host HCI return code if the controller 1892 * rejected the request; 1893 * A BLE host core return code on unexpected 1894 * error. 1895 */ 1896 int ble_gap_unpair_oldest_peer(void); 1897 1898 #define BLE_GAP_PRIVATE_MODE_NETWORK 0 1899 #define BLE_GAP_PRIVATE_MODE_DEVICE 1 1900 1901 /** 1902 * Set privacy mode for specified peer device 1903 * 1904 * @param peer_addr Peer device address 1905 * @param priv_mode Privacy mode to be used. Can be one of following 1906 * constants: 1907 * - BLE_GAP_PRIVATE_MODE_NETWORK 1908 * - BLE_GAP_PRIVATE_MODE_DEVICE 1909 * 1910 * @return 0 on success; nonzero on failure. 1911 */ 1912 int ble_gap_set_priv_mode(const ble_addr_t *peer_addr, uint8_t priv_mode); 1913 1914 #define BLE_GAP_LE_PHY_1M 1 1915 #define BLE_GAP_LE_PHY_2M 2 1916 #define BLE_GAP_LE_PHY_CODED 3 1917 /** 1918 * Read PHYs used for specified connection. 1919 * 1920 * On success output parameters are filled with information about used PHY type. 1921 * 1922 * @param conn_handle Connection handle 1923 * @param tx_phy TX PHY used. Can be one of following constants: 1924 * - BLE_GAP_LE_PHY_1M 1925 * - BLE_GAP_LE_PHY_2M 1926 * - BLE_GAP_LE_PHY_CODED 1927 * @param rx_phy RX PHY used. Can be one of following constants: 1928 * - BLE_GAP_LE_PHY_1M 1929 * - BLE_GAP_LE_PHY_2M 1930 * - BLE_GAP_LE_PHY_CODED 1931 * 1932 * @return 0 on success; nonzero on failure. 1933 */ 1934 int ble_gap_read_le_phy(uint16_t conn_handle, uint8_t *tx_phy, uint8_t *rx_phy); 1935 1936 #define BLE_GAP_LE_PHY_1M_MASK 0x01 1937 #define BLE_GAP_LE_PHY_2M_MASK 0x02 1938 #define BLE_GAP_LE_PHY_CODED_MASK 0x04 1939 #define BLE_GAP_LE_PHY_ANY_MASK 0x0F 1940 /** 1941 * Set preferred default PHYs to be used for connections. 1942 * 1943 * @params tx_phys_mask Preferred TX PHY. Can be mask of following 1944 * constants: 1945 * - BLE_GAP_LE_PHY_1M_MASK 1946 * - BLE_GAP_LE_PHY_2M_MASK 1947 * - BLE_GAP_LE_PHY_CODED_MASK 1948 * - BLE_GAP_LE_PHY_ANY_MASK 1949 * @params rx_phys_mask Preferred RX PHY. Can be mask of following 1950 * constants: 1951 * - BLE_GAP_LE_PHY_1M_MASK 1952 * - BLE_GAP_LE_PHY_2M_MASK 1953 * - BLE_GAP_LE_PHY_CODED_MASK 1954 * - BLE_GAP_LE_PHY_ANY_MASK 1955 1956 * @return 0 on success; nonzero on failure. 1957 */ 1958 int ble_gap_set_prefered_default_le_phy(uint8_t tx_phys_mask, 1959 uint8_t rx_phys_mask); 1960 1961 #define BLE_GAP_LE_PHY_CODED_ANY 0 1962 #define BLE_GAP_LE_PHY_CODED_S2 1 1963 #define BLE_GAP_LE_PHY_CODED_S8 2 1964 /** 1965 * Set preferred PHYs to be used for connection. 1966 * 1967 * @param conn_handle Connection handle 1968 * @params tx_phys_mask Preferred TX PHY. Can be mask of following 1969 * constants: 1970 * - BLE_GAP_LE_PHY_1M_MASK 1971 * - BLE_GAP_LE_PHY_2M_MASK 1972 * - BLE_GAP_LE_PHY_CODED_MASK 1973 * - BLE_GAP_LE_PHY_ANY_MASK 1974 * @params rx_phys_mask Preferred RX PHY. Can be mask of following 1975 * constants: 1976 * - BLE_GAP_LE_PHY_1M_MASK 1977 * - BLE_GAP_LE_PHY_2M_MASK 1978 * - BLE_GAP_LE_PHY_CODED_MASK 1979 * - BLE_GAP_LE_PHY_ANY_MASK 1980 * @param phy_opts Additional PHY options. Valid values are: 1981 * - BLE_GAP_LE_PHY_CODED_ANY 1982 * - BLE_GAP_LE_PHY_CODED_S2 1983 * - BLE_GAP_LE_PHY_CODED_S8 1984 * 1985 * @return 0 on success; nonzero on failure. 1986 */ 1987 int ble_gap_set_prefered_le_phy(uint16_t conn_handle, uint8_t tx_phys_mask, 1988 uint8_t rx_phys_mask, uint16_t phy_opts); 1989 1990 /** 1991 * Event listener structure 1992 * 1993 * This should be used as an opaque structure and not modified manually. 1994 */ 1995 struct ble_gap_event_listener { 1996 ble_gap_event_fn *fn; 1997 void *arg; 1998 SLIST_ENTRY(ble_gap_event_listener) link; 1999 }; 2000 2001 /** 2002 * Registers listener for GAP events 2003 * 2004 * On success listener structure will be initialized automatically and does not 2005 * need to be initialized prior to calling this function. To change callback 2006 * and/or argument unregister listener first and register it again. 2007 * 2008 * @param listener Listener structure 2009 * @param fn Callback function 2010 * @param arg Callback argument 2011 * 2012 * @return 0 on success 2013 * BLE_HS_EINVAL if no callback is specified 2014 * BLE_HS_EALREADY if listener is already registered 2015 */ 2016 int ble_gap_event_listener_register(struct ble_gap_event_listener *listener, 2017 ble_gap_event_fn *fn, void *arg); 2018 2019 /** 2020 * Unregisters listener for GAP events 2021 * 2022 * @param listener Listener structure 2023 * 2024 * @return 0 on success 2025 * BLE_HS_ENOENT if listener was not registered 2026 */ 2027 int ble_gap_event_listener_unregister(struct ble_gap_event_listener *listener); 2028 2029 /** 2030 * Get the default connection parameters 2031 * 2032 * @conn_params address of connection parameters 2033 * 2034 * @return void 2035 * 2036 */ 2037 2038 void ble_gap_init_conn_params(struct ble_gap_conn_params *conn_params); 2039 2040 #ifdef __cplusplus 2041 } 2042 #endif 2043 2044 /** 2045 * @} 2046 */ 2047 2048 #endif