1 /** @file
2 * @brief Bluetooth connection handling
3 */
4
5 /*
6 * Copyright (c) 2015-2016 Intel Corporation
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_
11 #define ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_
12
13 /**
14 * @brief Connection management
15 * @defgroup bt_conn Connection management
16 * @ingroup bluetooth
17 * @{
18 */
19
20 #include <stdbool.h>
21
22 #include <bluetooth/bluetooth.h>
23 #include <bluetooth/hci_err.h>
24 #include <bluetooth/addr.h>
25 #include <bluetooth/gap.h>
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 #if 0
32 /** LE Advertising Parameters. */
33 struct bt_le_adv_param {
34 /** Bit-field of advertising options */
35 u8_t options;
36
37 /** Minimum Advertising Interval (N * 0.625) */
38 u16_t interval_min;
39
40 /** Maximum Advertising Interval (N * 0.625) */
41 u16_t interval_max;
42
43 /** Optional predefined (random) own address. Currently
44 * the only permitted use of this is for NRPA with
45 * non-connectable advertising.
46 */
47 const bt_addr_t *own_addr;
48 };
49 #endif
50
51 /** Opaque type representing a connection to a remote device */
52 struct bt_conn;
53
54 /** Connection parameters for LE connections */
55 struct bt_le_conn_param {
56 u16_t interval_min;
57 u16_t interval_max;
58 u16_t latency;
59 u16_t timeout;
60 };
61
62 /** @brief Initialize connection parameters
63 *
64 * @param int_min Minimum Connection Interval (N * 1.25 ms)
65 * @param int_max Maximum Connection Interval (N * 1.25 ms)
66 * @param lat Connection Latency
67 * @param to Supervision Timeout (N * 10 ms)
68 */
69 #define BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
70 { \
71 .interval_min = (int_min), \
72 .interval_max = (int_max), \
73 .latency = (lat), \
74 .timeout = (to), \
75 }
76
77 /** Helper to declare connection parameters inline
78 *
79 * @param int_min Minimum Connection Interval (N * 1.25 ms)
80 * @param int_max Maximum Connection Interval (N * 1.25 ms)
81 * @param lat Connection Latency
82 * @param to Supervision Timeout (N * 10 ms)
83 */
84 #define BT_LE_CONN_PARAM(int_min, int_max, lat, to) \
85 ((struct bt_le_conn_param[]) { \
86 BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
87 })
88
89 /** Default LE connection parameters:
90 * Connection Interval: 30-50 ms
91 * Latency: 0
92 * Timeout: 4 s
93 */
94 #define BT_LE_CONN_PARAM_DEFAULT BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, \
95 BT_GAP_INIT_CONN_INT_MAX, \
96 0, 400)
97
98 /** Connection PHY information for LE connections */
99 struct bt_conn_le_phy_info {
100 u8_t tx_phy; /** Connection transmit PHY */
101 u8_t rx_phy; /** Connection receive PHY */
102 };
103
104 /** Preferred PHY parameters for LE connections */
105 struct bt_conn_le_phy_param {
106 u8_t pref_tx_phy; /** Bitmask of preferred transmit PHYs */
107 u8_t pref_rx_phy; /** Bitmask of preferred receive PHYs */
108 };
109
110 /** Initialize PHY parameters
111 *
112 * @param _pref_tx_phy Bitmask of preferred transmit PHYs.
113 * @param _pref_rx_phy Bitmask of preferred receive PHYs.
114 */
115 #define BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
116 { \
117 .pref_tx_phy = (_pref_tx_phy), \
118 .pref_rx_phy = (_pref_rx_phy), \
119 }
120
121 /** Helper to declare PHY parameters inline
122 *
123 * @param _pref_tx_phy Bitmask of preferred transmit PHYs.
124 * @param _pref_rx_phy Bitmask of preferred receive PHYs.
125 */
126 #define BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy) \
127 ((struct bt_conn_le_phy_param []) { \
128 BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
129 })
130
131 /** Only LE 1M PHY */
132 #define BT_CONN_LE_PHY_PARAM_1M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M, \
133 BT_GAP_LE_PHY_1M)
134
135 /** Only LE 2M PHY */
136 #define BT_CONN_LE_PHY_PARAM_2M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_2M, \
137 BT_GAP_LE_PHY_2M)
138
139 /** Only LE Coded PHY. */
140 #define BT_CONN_LE_PHY_PARAM_CODED BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_CODED, \
141 BT_GAP_LE_PHY_CODED)
142
143 /** All LE PHYs. */
144 #define BT_CONN_LE_PHY_PARAM_ALL BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M | \
145 BT_GAP_LE_PHY_2M | \
146 BT_GAP_LE_PHY_CODED, \
147 BT_GAP_LE_PHY_1M | \
148 BT_GAP_LE_PHY_2M | \
149 BT_GAP_LE_PHY_CODED)
150
151 /** Connection data length information for LE connections */
152 struct bt_conn_le_data_len_info {
153 /** Maximum Link Layer transmission payload size in bytes. */
154 u16_t tx_max_len;
155 /** Maximum Link Layer transmission payload time in us. */
156 u16_t tx_max_time;
157 /** Maximum Link Layer reception payload size in bytes. */
158 u16_t rx_max_len;
159 /** Maximum Link Layer reception payload time in us. */
160 u16_t rx_max_time;
161 };
162
163 /** Connection data length parameters for LE connections */
164 struct bt_conn_le_data_len_param {
165 /** Maximum Link Layer transmission payload size in bytes. */
166 u16_t tx_max_len;
167 /** Maximum Link Layer transmission payload time in us. */
168 u16_t tx_max_time;
169 };
170
171 /** Initialize transmit data length parameters
172 *
173 * @param _tx_max_len Maximum Link Layer transmission payload size in bytes.
174 * @param _tx_max_time Maximum Link Layer transmission payload time in us.
175 */
176 #define BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
177 { \
178 .tx_max_len = (_tx_max_len), \
179 .tx_max_time = (_tx_max_time), \
180 }
181
182 /** Helper to declare transmit data length parameters inline
183 *
184 * @param _tx_max_len Maximum Link Layer transmission payload size in bytes.
185 * @param _tx_max_time Maximum Link Layer transmission payload time in us.
186 */
187 #define BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time) \
188 ((struct bt_conn_le_data_len_param[]) { \
189 BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
190 })
191
192 /** Default LE data length parameters. */
193 #define BT_LE_DATA_LEN_PARAM_DEFAULT \
194 BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_DEFAULT, \
195 BT_GAP_DATA_TIME_DEFAULT)
196
197 /** Maximum LE data length parameters. */
198 #define BT_LE_DATA_LEN_PARAM_MAX \
199 BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_MAX, \
200 BT_GAP_DATA_TIME_MAX)
201
202 /** @brief Increment a connection's reference count.
203 *
204 * Increment the reference count of a connection object.
205 *
206 * @param conn Connection object.
207 *
208 * @return Connection object with incremented reference count.
209 */
210 struct bt_conn *bt_conn_ref(struct bt_conn *conn);
211
212 /** @brief Decrement a connection's reference count.
213 *
214 * Decrement the reference count of a connection object.
215 *
216 * @param conn Connection object.
217 */
218 void bt_conn_unref(struct bt_conn *conn);
219
220 /** @brief Iterate through all existing connections.
221 *
222 * @param type Connection Type
223 * @param func Function to call for each connection.
224 * @param data Data to pass to the callback function.
225 */
226 void bt_conn_foreach(int type, void (*func)(struct bt_conn *conn, void *data),
227 void *data);
228
229 /** @brief Look up an existing connection by address.
230 *
231 * Look up an existing connection based on the remote address.
232 *
233 * The caller gets a new reference to the connection object which must be
234 * released with bt_conn_unref() once done using the object.
235 *
236 * @param id Local identity (in most cases BT_ID_DEFAULT).
237 * @param peer Remote address.
238 *
239 * @return Connection object or NULL if not found.
240 */
241 struct bt_conn *bt_conn_lookup_addr_le(u8_t id, const bt_addr_le_t *peer);
242
243 /** @brief Get destination (peer) address of a connection.
244 *
245 * @param conn Connection object.
246 *
247 * @return Destination address.
248 */
249 const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn);
250
251 /** @brief Get array index of a connection
252 *
253 * This function is used to map bt_conn to index of an array of
254 * connections. The array has CONFIG_BT_MAX_CONN elements.
255 *
256 * @param conn Connection object.
257 *
258 * @return Index of the connection object.
259 * The range of the returned value is 0..CONFIG_BT_MAX_CONN-1
260 */
261 u8_t bt_conn_index(struct bt_conn *conn);
262
263 /** Connection Type */
264 enum {
265 /** LE Connection Type */
266 BT_CONN_TYPE_LE = BIT(0),
267 /** BR/EDR Connection Type */
268 BT_CONN_TYPE_BR = BIT(1),
269 /** SCO Connection Type */
270 BT_CONN_TYPE_SCO = BIT(2),
271 /** All Connection Type */
272 BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR | BT_CONN_TYPE_SCO,
273 };
274
275 /** LE Connection Info Structure */
276 struct bt_conn_le_info {
277 /** Source (Local) Identity Address */
278 const bt_addr_le_t *src;
279 /** Destination (Remote) Identity Address or remote Resolvable Private
280 * Address (RPA) before identity has been resolved.
281 */
282 const bt_addr_le_t *dst;
283 /** Local device address used during connection setup. */
284 const bt_addr_le_t *local;
285 /** Remote device address used during connection setup. */
286 const bt_addr_le_t *remote;
287 u16_t interval; /** Connection interval */
288 u16_t latency; /** Connection slave latency */
289 u16_t timeout; /** Connection supervision timeout */
290
291 #if defined(CONFIG_BT_USER_PHY_UPDATE)
292 const struct bt_conn_le_phy_info *phy;
293 #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
294
295 #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
296 /* Connection maximum single fragment parameters */
297 const struct bt_conn_le_data_len_info *data_len;
298 #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
299 };
300
301 /** BR/EDR Connection Info Structure */
302 struct bt_conn_br_info {
303 const bt_addr_t *dst; /** Destination (Remote) BR/EDR address */
304 };
305
306 /** Connection role (master or slave) */
307 enum {
308 BT_CONN_ROLE_MASTER,
309 BT_CONN_ROLE_SLAVE,
310 };
311
312 /** Connection Info Structure */
313 struct bt_conn_info {
314 /** Connection Type. */
315 u8_t type;
316 /** Connection Role. */
317 u8_t role;
318 /** Which local identity the connection was created with */
319 u8_t id;
320 /** Connection Type specific Info.*/
321 union {
322 /** LE Connection specific Info. */
323 struct bt_conn_le_info le;
324 /** BR/EDR Connection specific Info. */
325 struct bt_conn_br_info br;
326 };
327 };
328
329 /** LE Connection Remote Info Structure */
330 struct bt_conn_le_remote_info {
331
332 /** Remote LE feature set (bitmask). */
333 const u8_t *features;
334 };
335
336 /** BR/EDR Connection Remote Info structure */
337 struct bt_conn_br_remote_info {
338
339 /** Remote feature set (pages of bitmasks). */
340 const u8_t *features;
341
342 /** Number of pages in the remote feature set. */
343 u8_t num_pages;
344 };
345
346 /** @brief Connection Remote Info Structure
347 *
348 * @note The version, manufacturer and subversion fields will only contain
349 * valid data if :option:`CONFIG_BT_REMOTE_VERSION` is enabled.
350 */
351 struct bt_conn_remote_info {
352 /** Connection Type */
353 u8_t type;
354
355 /** Remote Link Layer version */
356 u8_t version;
357
358 /** Remote manufacturer identifier */
359 u16_t manufacturer;
360
361 /** Per-manufacturer unique revision */
362 u16_t subversion;
363
364 union {
365 /** LE connection remote info */
366 struct bt_conn_le_remote_info le;
367
368 /** BR/EDR connection remote info */
369 struct bt_conn_br_remote_info br;
370 };
371 };
372
373 /** @brief Get connection info
374 *
375 * @param conn Connection object.
376 * @param info Connection info object.
377 *
378 * @return Zero on success or (negative) error code on failure.
379 */
380 int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info);
381
382 /** @brief Get connection info for the remote device.
383 *
384 * @param conn Connection object.
385 * @param remote_info Connection remote info object.
386 *
387 * @note In order to retrieve the remote version (version, manufacturer
388 * and subversion) :option:`CONFIG_BT_REMOTE_VERSION` must be enabled
389 *
390 * @note The remote information is exchanged directly after the connection has
391 * been established. The application can be notified about when the remote
392 * information is available through the remote_info_available callback.
393 *
394 * @return Zero on success or (negative) error code on failure.
395 * @return -EBUSY The remote information is not yet available.
396 */
397 int bt_conn_get_remote_info(struct bt_conn *conn,
398 struct bt_conn_remote_info *remote_info);
399
400 /** @brief Update the connection parameters.
401 *
402 * @param conn Connection object.
403 * @param param Updated connection parameters.
404 *
405 * @return Zero on success or (negative) error code on failure.
406 */
407 int bt_conn_le_param_update(struct bt_conn *conn,
408 const struct bt_le_conn_param *param);
409
410 /** @brief Update the connection transmit data length parameters.
411 *
412 * @param conn Connection object.
413 * @param param Updated data length parameters.
414 *
415 * @return Zero on success or (negative) error code on failure.
416 */
417 int bt_conn_le_data_len_update(struct bt_conn *conn,
418 const struct bt_conn_le_data_len_param *param);
419
420 /** @brief Update the connection PHY parameters.
421 *
422 * @param conn Connection object.
423 * @param param Updated connection parameters.
424 *
425 * @return Zero on success or (negative) error code on failure.
426 */
427 int bt_conn_le_phy_update(struct bt_conn *conn,
428 const struct bt_conn_le_phy_param *param);
429
430 /** @brief Disconnect from a remote device or cancel pending connection.
431 *
432 * Disconnect an active connection with the specified reason code or cancel
433 * pending outgoing connection.
434 *
435 * @param conn Connection to disconnect.
436 * @param reason Reason code for the disconnection.
437 *
438 * @return Zero on success or (negative) error code on failure.
439 */
440 int bt_conn_disconnect(struct bt_conn *conn, u8_t reason);
441
442 enum {
443 /** Convenience value when no options are specified. */
444 BT_CONN_LE_OPT_NONE = 0,
445
446 /** @brief Enable LE Coded PHY.
447 *
448 * Enable scanning on the LE Coded PHY.
449 */
450 BT_CONN_LE_OPT_CODED = BIT(0),
451
452 /** @brief Disable LE 1M PHY.
453 *
454 * Disable scanning on the LE 1M PHY.
455 *
456 * @note Requires @ref BT_CONN_LE_OPT_CODED.
457 */
458 BT_CONN_LE_OPT_NO_1M = BIT(1),
459 };
460
461 struct bt_conn_le_create_param {
462
463 /** Bit-field of create connection options. */
464 bt_u32_t options;
465
466 /** Scan interval (N * 0.625 ms) */
467 u16_t interval;
468
469 /** Scan window (N * 0.625 ms) */
470 u16_t window;
471
472 /** @brief Scan interval LE Coded PHY (N * 0.625 MS)
473 *
474 * Set zero to use same as LE 1M PHY scan interval
475 */
476 u16_t interval_coded;
477
478 /** @brief Scan window LE Coded PHY (N * 0.625 MS)
479 *
480 * Set zero to use same as LE 1M PHY scan window.
481 */
482 u16_t window_coded;
483
484 /** @brief Connection initiation timeout (N * 10 MS)
485 *
486 * Set zero to use the default :option:`CONFIG_BT_CREATE_CONN_TIMEOUT`
487 * timeout.
488 *
489 * @note Unused in @ref bt_conn_create_auto_le
490 */
491 u16_t timeout;
492 };
493
494 /** @brief Initialize create connection parameters
495 *
496 * @param _options Create connection options.
497 * @param _interval Create connection scan interval (N * 0.625 ms).
498 * @param _window Create connection scan window (N * 0.625 ms).
499 */
500 #define BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
501 { \
502 .options = (_options), \
503 .interval = (_interval), \
504 .window = (_window), \
505 .interval_coded = 0, \
506 .window_coded = 0, \
507 .timeout = 0, \
508 }
509
510 /** Helper to declare create connection parameters inline
511 *
512 * @param _options Create connection options.
513 * @param _interval Create connection scan interval (N * 0.625 ms).
514 * @param _window Create connection scan window (N * 0.625 ms).
515 */
516 #define BT_CONN_LE_CREATE_PARAM(_options, _interval, _window) \
517 ((struct bt_conn_le_create_param[]) { \
518 BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
519 })
520
521 /** Default LE create connection parameters.
522 * Scan continuously by setting scan interval equal to scan window.
523 */
524 #define BT_CONN_LE_CREATE_CONN \
525 BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
526 BT_GAP_SCAN_FAST_INTERVAL, \
527 BT_GAP_SCAN_FAST_INTERVAL)
528
529 /** Default LE create connection using whitelist parameters.
530 * Scan window: 30 ms.
531 * Scan interval: 60 ms.
532 */
533 #define BT_CONN_LE_CREATE_CONN_AUTO \
534 BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
535 BT_GAP_SCAN_FAST_INTERVAL, \
536 BT_GAP_SCAN_FAST_WINDOW)
537
538 /** @brief Initiate an LE connection to a remote device.
539 *
540 * Allows initiate new LE link to remote peer using its address.
541 *
542 * The caller gets a new reference to the connection object which must be
543 * released with bt_conn_unref() once done using the object.
544 *
545 * This uses the General Connection Establishment procedure.
546 *
547 * @param[in] peer Remote address.
548 * @param[in] create_param Create connection parameters.
549 * @param[in] conn_param Initial connection parameters.
550 * @param[out] conn Valid connection object on success.
551 *
552 * @return Zero on success or (negative) error code on failure.
553 */
554 int bt_conn_le_create(const bt_addr_le_t *peer,
555 const struct bt_conn_le_create_param *create_param,
556 const struct bt_le_conn_param *conn_param,
557 struct bt_conn **conn);
558
559 __deprecated static inline
bt_conn_create_le(const bt_addr_le_t * peer,const struct bt_le_conn_param * conn_param)560 struct bt_conn *bt_conn_create_le(const bt_addr_le_t *peer,
561 const struct bt_le_conn_param *conn_param)
562 {
563 struct bt_conn *conn;
564 struct bt_conn_le_create_param param = BT_CONN_LE_CREATE_PARAM_INIT(
565 BT_CONN_LE_OPT_NONE,
566 BT_GAP_SCAN_FAST_INTERVAL,
567 BT_GAP_SCAN_FAST_INTERVAL);
568
569 if (bt_conn_le_create(peer, ¶m, conn_param,
570 &conn)) {
571 return NULL;
572 }
573
574 return conn;
575 }
576
577 /** @brief Automatically connect to remote devices in whitelist.
578 *
579 * This uses the Auto Connection Establishment procedure.
580 * The procedure will continue until a single connection is established or the
581 * procedure is stopped through @ref bt_conn_create_auto_stop.
582 * To establish connections to all devices in the whitelist the procedure
583 * should be started again in the connected callback after a new connection has
584 * been established.
585 *
586 * @param create_param Create connection parameters
587 * @param conn_param Initial connection parameters.
588 *
589 * @return Zero on success or (negative) error code on failure.
590 * @return -ENOMEM No free connection object available.
591 */
592 int bt_conn_le_create_auto(const struct bt_conn_le_create_param *create_param,
593 const struct bt_le_conn_param *conn_param);
594
595 __deprecated static inline
bt_conn_create_auto_le(const struct bt_le_conn_param * conn_param)596 int bt_conn_create_auto_le(const struct bt_le_conn_param *conn_param)
597 {
598 struct bt_conn_le_create_param param = BT_CONN_LE_CREATE_PARAM_INIT(
599 BT_CONN_LE_OPT_NONE,
600 BT_GAP_SCAN_FAST_INTERVAL,
601 BT_GAP_SCAN_FAST_WINDOW);
602
603 return bt_conn_le_create_auto(¶m, conn_param);
604 }
605
606 /** @brief Stop automatic connect creation.
607 *
608 * @return Zero on success or (negative) error code on failure.
609 */
610 int bt_conn_create_auto_stop(void);
611
612 /** @brief Automatically connect to remote device if it's in range.
613 *
614 * This function enables/disables automatic connection initiation.
615 * Every time the device loses the connection with peer, this connection
616 * will be re-established if connectable advertisement from peer is received.
617 *
618 * @note Auto connect is disabled during explicit scanning.
619 *
620 * @param addr Remote Bluetooth address.
621 * @param param If non-NULL, auto connect is enabled with the given
622 * parameters. If NULL, auto connect is disabled.
623 *
624 * @return Zero on success or error code otherwise.
625 */
626 int bt_le_set_auto_conn(const bt_addr_le_t *addr,
627 const struct bt_le_conn_param *param);
628
629 /** @brief Initiate directed advertising to a remote device
630 *
631 * Allows initiating a new LE connection to remote peer with the remote
632 * acting in central role and the local device in peripheral role.
633 *
634 * The advertising type will either be BT_LE_ADV_DIRECT_IND, or
635 * BT_LE_ADV_DIRECT_IND_LOW_DUTY if the BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY
636 * option was used as part of the advertising parameters.
637 *
638 * In case of high duty cycle this will result in a callback with
639 * connected() with a new connection or with an error.
640 *
641 * The advertising may be canceled with bt_conn_disconnect().
642 *
643 * The caller gets a new reference to the connection object which must be
644 * released with bt_conn_unref() once done using the object.
645 *
646 * @param peer Remote address.
647 * @param param Directed advertising parameters.
648 *
649 * @return Valid connection object on success or NULL otherwise.
650 */
651 __deprecated static inline
bt_conn_create_slave_le(const bt_addr_le_t * peer,const struct bt_le_adv_param * param)652 struct bt_conn *bt_conn_create_slave_le(const bt_addr_le_t *peer,
653 const struct bt_le_adv_param *param)
654 {
655 struct bt_le_adv_param adv_param = *param;
656
657 adv_param.options |= (BT_LE_ADV_OPT_CONNECTABLE |
658 BT_LE_ADV_OPT_ONE_TIME);
659 adv_param.peer = peer;
660
661 if (!bt_le_adv_start(&adv_param, NULL, 0, NULL, 0)) {
662 return NULL;
663 }
664
665 return bt_conn_lookup_addr_le(param->id, peer);
666 }
667
668 /** Security level. */
669 typedef enum __packed {
670 /** Level 0: Only for BR/EDR special cases, like SDP */
671 BT_SECURITY_L0,
672 /** Level 1: No encryption and no authentication. */
673 BT_SECURITY_L1,
674 /** Level 2: Encryption and no authentication (no MITM). */
675 BT_SECURITY_L2,
676 /** Level 3: Encryption and authentication (MITM). */
677 BT_SECURITY_L3,
678 /** Level 4: Authenticated Secure Connections and 128-bit key. */
679 BT_SECURITY_L4,
680
681 BT_SECURITY_NONE __deprecated = BT_SECURITY_L0,
682 BT_SECURITY_LOW __deprecated = BT_SECURITY_L1,
683 BT_SECURITY_MEDIUM __deprecated = BT_SECURITY_L2,
684 BT_SECURITY_HIGH __deprecated = BT_SECURITY_L3,
685 BT_SECURITY_FIPS __deprecated = BT_SECURITY_L4,
686
687 /** Bit to force new pairing procedure, bit-wise OR with requested
688 * security level.
689 */
690 BT_SECURITY_FORCE_PAIR = BIT(7),
691 } bt_security_t;
692
693 /** @brief Set security level for a connection.
694 *
695 * This function enable security (encryption) for a connection. If device is
696 * already paired with sufficiently strong key encryption will be enabled. If
697 * link is already encrypted with sufficiently strong key this function does
698 * nothing.
699 *
700 * If device is not paired pairing will be initiated. If device is paired and
701 * keys are too weak but input output capabilities allow for strong enough keys
702 * pairing will be initiated.
703 *
704 * This function may return error if required level of security is not possible
705 * to achieve due to local or remote device limitation (e.g., input output
706 * capabilities), or if the maximum number of paired devices has been reached.
707 *
708 * This function may return error if the pairing procedure has already been
709 * initiated by the local device or the peer device.
710 *
711 * @param conn Connection object.
712 * @param sec Requested security level.
713 *
714 * @return 0 on success or negative error
715 */
716 int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec);
717
718 /** @brief Get security level for a connection.
719 *
720 * @return Connection security level
721 */
722 bt_security_t bt_conn_get_security(struct bt_conn *conn);
723
bt_conn_security(struct bt_conn * conn,bt_security_t sec)724 static inline int __deprecated bt_conn_security(struct bt_conn *conn,
725 bt_security_t sec)
726 {
727 return bt_conn_set_security(conn, sec);
728 }
729
730 /** @brief Get encryption key size.
731 *
732 * This function gets encryption key size.
733 * If there is no security (encryption) enabled 0 will be returned.
734 *
735 * @param conn Existing connection object.
736 *
737 * @return Encryption key size.
738 */
739 u8_t bt_conn_enc_key_size(struct bt_conn *conn);
740
741 enum bt_security_err {
742 /** Security procedure successful. */
743 BT_SECURITY_ERR_SUCCESS,
744
745 /** Authentication failed. */
746 BT_SECURITY_ERR_AUTH_FAIL,
747
748 /** PIN or encryption key is missing. */
749 BT_SECURITY_ERR_PIN_OR_KEY_MISSING,
750
751 /** OOB data is not available. */
752 BT_SECURITY_ERR_OOB_NOT_AVAILABLE,
753
754 /** The requested security level could not be reached. */
755 BT_SECURITY_ERR_AUTH_REQUIREMENT,
756
757 /** Pairing is not supported */
758 BT_SECURITY_ERR_PAIR_NOT_SUPPORTED,
759
760 /** Pairing is not allowed. */
761 BT_SECURITY_ERR_PAIR_NOT_ALLOWED,
762
763 /** Invalid parameters. */
764 BT_SECURITY_ERR_INVALID_PARAM,
765
766 /** Pairing failed but the exact reason could not be specified. */
767 BT_SECURITY_ERR_UNSPECIFIED,
768 };
769
770 /** @brief Connection callback structure.
771 *
772 * This structure is used for tracking the state of a connection.
773 * It is registered with the help of the bt_conn_cb_register() API.
774 * It's permissible to register multiple instances of this @ref bt_conn_cb
775 * type, in case different modules of an application are interested in
776 * tracking the connection state. If a callback is not of interest for
777 * an instance, it may be set to NULL and will as a consequence not be
778 * used for that instance.
779 */
780 struct bt_conn_cb {
781 /** @brief A new connection has been established.
782 *
783 * This callback notifies the application of a new connection.
784 * In case the err parameter is non-zero it means that the
785 * connection establishment failed.
786 *
787 * @param conn New connection object.
788 * @param err HCI error. Zero for success, non-zero otherwise.
789 *
790 * @p err can mean either of the following:
791 * - @ref BT_HCI_ERR_UNKNOWN_CONN_ID Creating the connection started by
792 * @ref bt_conn_create_le was canceled either by the user through
793 * @ref bt_conn_disconnect or by the timeout in the host through
794 * @ref bt_conn_le_create_param timeout parameter, which defaults to
795 * :option:`CONFIG_BT_CREATE_CONN_TIMEOUT` seconds.
796 * - @p BT_HCI_ERR_ADV_TIMEOUT High duty cycle directed connectable
797 * advertiser started by @ref bt_le_adv_start failed to be connected
798 * within the timeout.
799 */
800 void (*connected)(struct bt_conn *conn, u8_t err);
801
802 /** @brief A connection has been disconnected.
803 *
804 * This callback notifies the application that a connection
805 * has been disconnected.
806 *
807 * When this callback is called the stack still has one reference to
808 * the connection object. If the application in this callback tries to
809 * start either a connectable advertiser or create a new connection
810 * this might fail because there are no free connection objects
811 * available.
812 * To avoid this issue it is recommended to either start connectable
813 * advertise or create a new connection using @ref k_work_submit or
814 * increase :option:`CONFIG_BT_MAX_CONN`.
815 *
816 * @param conn Connection object.
817 * @param reason HCI reason for the disconnection.
818 */
819 void (*disconnected)(struct bt_conn *conn, u8_t reason);
820
821 /** @brief LE connection parameter update request.
822 *
823 * This callback notifies the application that a remote device
824 * is requesting to update the connection parameters. The
825 * application accepts the parameters by returning true, or
826 * rejects them by returning false. Before accepting, the
827 * application may also adjust the parameters to better suit
828 * its needs.
829 *
830 * It is recommended for an application to have just one of these
831 * callbacks for simplicity. However, if an application registers
832 * multiple it needs to manage the potentially different
833 * requirements for each callback. Each callback gets the
834 * parameters as returned by previous callbacks, i.e. they are not
835 * necessarily the same ones as the remote originally sent.
836 *
837 * @param conn Connection object.
838 * @param param Proposed connection parameters.
839 *
840 * @return true to accept the parameters, or false to reject them.
841 */
842 bool (*le_param_req)(struct bt_conn *conn,
843 struct bt_le_conn_param *param);
844
845 /** @brief The parameters for an LE connection have been updated.
846 *
847 * This callback notifies the application that the connection
848 * parameters for an LE connection have been updated.
849 *
850 * @param conn Connection object.
851 * @param interval Connection interval.
852 * @param latency Connection latency.
853 * @param timeout Connection supervision timeout.
854 */
855 void (*le_param_updated)(struct bt_conn *conn, u16_t interval,
856 u16_t latency, u16_t timeout);
857 #if defined(CONFIG_BT_SMP)
858 /** @brief Remote Identity Address has been resolved.
859 *
860 * This callback notifies the application that a remote
861 * Identity Address has been resolved
862 *
863 * @param conn Connection object.
864 * @param rpa Resolvable Private Address.
865 * @param identity Identity Address.
866 */
867 void (*identity_resolved)(struct bt_conn *conn,
868 const bt_addr_le_t *rpa,
869 const bt_addr_le_t *identity);
870 #endif /* CONFIG_BT_SMP */
871 #if defined(CONFIG_BT_SMP) || defined(CONFIG_BT_BREDR)
872 /** @brief The security level of a connection has changed.
873 *
874 * This callback notifies the application that the security level
875 * of a connection has changed.
876 *
877 * @param conn Connection object.
878 * @param level New security level of the connection.
879 * @param err Security error. Zero for success, non-zero otherwise.
880 */
881 void (*security_changed)(struct bt_conn *conn, bt_security_t level,
882 enum bt_security_err err);
883 #endif /* defined(CONFIG_BT_SMP) || defined(CONFIG_BT_BREDR) */
884
885 #if defined(CONFIG_BT_REMOTE_INFO)
886 /** @brief Remote information procedures has completed.
887 *
888 * This callback notifies the application that the remote information
889 * has been retrieved from the remote peer.
890 *
891 * @param conn Connection object.
892 * @param remote_info Connection information of remote device.
893 */
894 void (*remote_info_available)(struct bt_conn *conn,
895 struct bt_conn_remote_info *remote_info);
896 #endif /* defined(CONFIG_BT_REMOTE_INFO) */
897
898 #if defined(CONFIG_BT_USER_PHY_UPDATE)
899 /** @brief The PHY of the connection has changed.
900 *
901 * This callback notifies the application that the PHY of the
902 * connection has changed.
903 *
904 * @param conn Connection object.
905 * @param info Connection LE PHY information.
906 */
907 void (*le_phy_updated)(struct bt_conn *conn,
908 struct bt_conn_le_phy_info *param);
909 #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
910
911 #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
912 /** @brief The data length parameters of the connection has changed.
913 *
914 * This callback notifies the application that the maximum Link Layer
915 * payload length or transmission time has changed.
916 *
917 * @param conn Connection object.
918 * @param info Connection data length information.
919 */
920 void (*le_data_len_updated)(struct bt_conn *conn,
921 struct bt_conn_le_data_len_info *info);
922 #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
923
924 struct bt_conn_cb *_next;
925 };
926
927 /** @brief Register connection callbacks.
928 *
929 * Register callbacks to monitor the state of connections.
930 *
931 * @param cb Callback struct.
932 */
933 void bt_conn_cb_register(struct bt_conn_cb *cb);
934
935 /** @brief Enable/disable bonding.
936 *
937 * Set/clear the Bonding flag in the Authentication Requirements of
938 * SMP Pairing Request/Response data.
939 * The initial value of this flag depends on BT_BONDABLE Kconfig setting.
940 * For the vast majority of applications calling this function shouldn't be
941 * needed.
942 *
943 * @param enable Value allowing/disallowing to be bondable.
944 */
945 void bt_set_bondable(bool enable);
946
947 /** @brief Allow/disallow remote OOB data to be used for pairing.
948 *
949 * Set/clear the OOB data flag for SMP Pairing Request/Response data.
950 * The initial value of this flag depends on BT_OOB_DATA_PRESENT Kconfig
951 * setting.
952 *
953 * @param enable Value allowing/disallowing remote OOB data.
954 */
955 void bt_set_oob_data_flag(bool enable);
956
957 /** @brief Set OOB Temporary Key to be used for pairing
958 *
959 * This function allows to set OOB data for the LE legacy pairing procedure.
960 * The function should only be called in response to the oob_data_request()
961 * callback provided that the legacy method is user pairing.
962 *
963 * @param conn Connection object
964 * @param tk Pointer to 16 byte long TK array
965 *
966 * @return Zero on success or -EINVAL if NULL
967 */
968 int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const u8_t *tk);
969
970 /** @brief Set OOB data during LE Secure Connections (SC) pairing procedure
971 *
972 * This function allows to set OOB data during the LE SC pairing procedure.
973 * The function should only be called in response to the oob_data_request()
974 * callback provided that LE SC method is used for pairing.
975 *
976 * The user should submit OOB data according to the information received in the
977 * callback. This may yield three different configurations: with only local OOB
978 * data present, with only remote OOB data present or with both local and
979 * remote OOB data present.
980 *
981 * @param conn Connection object
982 * @param oobd_local Local OOB data or NULL if not present
983 * @param oobd_remote Remote OOB data or NULL if not present
984 *
985 * @return Zero on success or error code otherwise, positive in case of
986 * protocol error or negative (POSIX) in case of stack internal error.
987 */
988 int bt_le_oob_set_sc_data(struct bt_conn *conn,
989 const struct bt_le_oob_sc_data *oobd_local,
990 const struct bt_le_oob_sc_data *oobd_remote);
991
992 /** @brief Get OOB data used for LE Secure Connections (SC) pairing procedure
993 *
994 * This function allows to get OOB data during the LE SC pairing procedure that
995 * were set by the bt_le_oob_set_sc_data() API.
996 *
997 * @note The OOB data will only be available as long as the connection object
998 * associated with it is valid.
999 *
1000 * @param conn Connection object
1001 * @param oobd_local Local OOB data or NULL if not set
1002 * @param oobd_remote Remote OOB data or NULL if not set
1003 *
1004 * @return Zero on success or error code otherwise, positive in case of
1005 * protocol error or negative (POSIX) in case of stack internal error.
1006 */
1007 int bt_le_oob_get_sc_data(struct bt_conn *conn,
1008 const struct bt_le_oob_sc_data **oobd_local,
1009 const struct bt_le_oob_sc_data **oobd_remote);
1010
1011 /** @def BT_PASSKEY_INVALID
1012 *
1013 * Special passkey value that can be used to disable a previously
1014 * set fixed passkey.
1015 */
1016 #define BT_PASSKEY_INVALID 0xffffffff
1017
1018 /** @brief Set a fixed passkey to be used for pairing.
1019 *
1020 * This API is only available when the CONFIG_BT_FIXED_PASSKEY
1021 * configuration option has been enabled.
1022 *
1023 * Sets a fixed passkey to be used for pairing. If set, the
1024 * pairing_confim() callback will be called for all incoming pairings.
1025 *
1026 * @param passkey A valid passkey (0 - 999999) or BT_PASSKEY_INVALID
1027 * to disable a previously set fixed passkey.
1028 *
1029 * @return 0 on success or a negative error code on failure.
1030 */
1031 int bt_passkey_set(unsigned int passkey);
1032
1033 /** Info Structure for OOB pairing */
1034 struct bt_conn_oob_info {
1035 /** Type of OOB pairing method */
1036 enum {
1037 /** LE legacy pairing */
1038 BT_CONN_OOB_LE_LEGACY,
1039
1040 /** LE SC pairing */
1041 BT_CONN_OOB_LE_SC,
1042 } type;
1043
1044 union {
1045 /** LE Secure Connections OOB pairing parameters */
1046 struct {
1047 /** OOB data configuration */
1048 enum {
1049 /** Local OOB data requested */
1050 BT_CONN_OOB_LOCAL_ONLY,
1051
1052 /** Remote OOB data requested */
1053 BT_CONN_OOB_REMOTE_ONLY,
1054
1055 /** Both local and remote OOB data requested */
1056 BT_CONN_OOB_BOTH_PEERS,
1057
1058 /** No OOB data requested */
1059 BT_CONN_OOB_NO_DATA,
1060 } oob_config;
1061 } lesc;
1062 };
1063 };
1064
1065 #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
1066 /** @brief Pairing request and pairing response info structure.
1067 *
1068 * This structure is the same for both smp_pairing_req and smp_pairing_rsp
1069 * and a subset of the packet data, except for the initial Code octet.
1070 * It is documented in Core Spec. Vol. 3, Part H, 3.5.1 and 3.5.2.
1071 */
1072 struct bt_conn_pairing_feat {
1073 /** IO Capability, Core Spec. Vol 3, Part H, 3.5.1, Table 3.4 */
1074 u8_t io_capability;
1075
1076 /** OOB data flag, Core Spec. Vol 3, Part H, 3.5.1, Table 3.5 */
1077 u8_t oob_data_flag;
1078
1079 /** AuthReq, Core Spec. Vol 3, Part H, 3.5.1, Fig. 3.3 */
1080 u8_t auth_req;
1081
1082 /** Maximum Encryption Key Size, Core Spec. Vol 3, Part H, 3.5.1 */
1083 u8_t max_enc_key_size;
1084
1085 /** Initiator Key Distribution/Generation, Core Spec. Vol 3, Part H,
1086 * 3.6.1, Fig. 3.11
1087 */
1088 u8_t init_key_dist;
1089
1090 /** Responder Key Distribution/Generation, Core Spec. Vol 3, Part H
1091 * 3.6.1, Fig. 3.11
1092 */
1093 u8_t resp_key_dist;
1094 };
1095 #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
1096
1097 /** Authenticated pairing callback structure */
1098 struct bt_conn_auth_cb {
1099 #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
1100 /** @brief Query to proceed incoming pairing or not.
1101 *
1102 * On any incoming pairing req/rsp this callback will be called for
1103 * the application to decide whether to allow for the pairing to
1104 * continue.
1105 *
1106 * The pairing info received from the peer is passed to assist
1107 * making the decision.
1108 *
1109 * As this callback is synchronous the application should return
1110 * a response value immediately. Otherwise it may affect the
1111 * timing during pairing. Hence, this information should not be
1112 * conveyed to the user to take action.
1113 *
1114 * The remaining callbacks are not affected by this, but do notice
1115 * that other callbacks can be called during the pairing. Eg. if
1116 * pairing_confirm is registered both will be called for Just-Works
1117 * pairings.
1118 *
1119 * This callback may be unregistered in which case pairing continues
1120 * as if the Kconfig flag was not set.
1121 *
1122 * This callback is not called for BR/EDR Secure Simple Pairing (SSP).
1123 *
1124 * @param conn Connection where pairing is initiated.
1125 * @param feat Pairing req/resp info.
1126 */
1127 enum bt_security_err (*pairing_accept)(struct bt_conn *conn,
1128 const struct bt_conn_pairing_feat *const feat);
1129 #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
1130
1131 /** @brief Display a passkey to the user.
1132 *
1133 * When called the application is expected to display the given
1134 * passkey to the user, with the expectation that the passkey will
1135 * then be entered on the peer device. The passkey will be in the
1136 * range of 0 - 999999, and is expected to be padded with zeroes so
1137 * that six digits are always shown. E.g. the value 37 should be
1138 * shown as 000037.
1139 *
1140 * This callback may be set to NULL, which means that the local
1141 * device lacks the ability do display a passkey. If set
1142 * to non-NULL the cancel callback must also be provided, since
1143 * this is the only way the application can find out that it should
1144 * stop displaying the passkey.
1145 *
1146 * @param conn Connection where pairing is currently active.
1147 * @param passkey Passkey to show to the user.
1148 */
1149 void (*passkey_display)(struct bt_conn *conn, unsigned int passkey);
1150
1151 /** @brief Request the user to enter a passkey.
1152 *
1153 * When called the user is expected to enter a passkey. The passkey
1154 * must be in the range of 0 - 999999, and should be expected to
1155 * be zero-padded, as that's how the peer device will typically be
1156 * showing it (e.g. 37 would be shown as 000037).
1157 *
1158 * Once the user has entered the passkey its value should be given
1159 * to the stack using the bt_conn_auth_passkey_entry() API.
1160 *
1161 * This callback may be set to NULL, which means that the local
1162 * device lacks the ability to enter a passkey. If set to non-NULL
1163 * the cancel callback must also be provided, since this is the
1164 * only way the application can find out that it should stop
1165 * requesting the user to enter a passkey.
1166 *
1167 * @param conn Connection where pairing is currently active.
1168 */
1169 void (*passkey_entry)(struct bt_conn *conn);
1170
1171 /** @brief Request the user to confirm a passkey.
1172 *
1173 * When called the user is expected to confirm that the given
1174 * passkey is also shown on the peer device.. The passkey will
1175 * be in the range of 0 - 999999, and should be zero-padded to
1176 * always be six digits (e.g. 37 would be shown as 000037).
1177 *
1178 * Once the user has confirmed the passkey to match, the
1179 * bt_conn_auth_passkey_confirm() API should be called. If the
1180 * user concluded that the passkey doesn't match the
1181 * bt_conn_auth_cancel() API should be called.
1182 *
1183 * This callback may be set to NULL, which means that the local
1184 * device lacks the ability to confirm a passkey. If set to non-NULL
1185 * the cancel callback must also be provided, since this is the
1186 * only way the application can find out that it should stop
1187 * requesting the user to confirm a passkey.
1188 *
1189 * @param conn Connection where pairing is currently active.
1190 * @param passkey Passkey to be confirmed.
1191 */
1192 void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey);
1193
1194 /** @brief Request the user to provide Out of Band (OOB) data.
1195 *
1196 * When called the user is expected to provide OOB data. The required
1197 * data are indicated by the information structure.
1198 *
1199 * For LE Secure Connections OOB pairing, the user should provide
1200 * local OOB data, remote OOB data or both depending on their
1201 * availability. Their value should be given to the stack using the
1202 * bt_le_oob_set_sc_data() API.
1203 *
1204 * This callback must be set to non-NULL in order to support OOB
1205 * pairing.
1206 *
1207 * @param conn Connection where pairing is currently active.
1208 * @param info OOB pairing information.
1209 */
1210 void (*oob_data_request)(struct bt_conn *conn,
1211 struct bt_conn_oob_info *info);
1212
1213 /** @brief Cancel the ongoing user request.
1214 *
1215 * This callback will be called to notify the application that it
1216 * should cancel any previous user request (passkey display, entry
1217 * or confirmation).
1218 *
1219 * This may be set to NULL, but must always be provided whenever the
1220 * passkey_display, passkey_entry passkey_confirm or pairing_confirm
1221 * callback has been provided.
1222 *
1223 * @param conn Connection where pairing is currently active.
1224 */
1225 void (*cancel)(struct bt_conn *conn);
1226
1227 /** @brief Request confirmation for an incoming pairing.
1228 *
1229 * This callback will be called to confirm an incoming pairing
1230 * request where none of the other user callbacks is applicable.
1231 *
1232 * If the user decides to accept the pairing the
1233 * bt_conn_auth_pairing_confirm() API should be called. If the
1234 * user decides to reject the pairing the bt_conn_auth_cancel() API
1235 * should be called.
1236 *
1237 * This callback may be set to NULL, which means that the local
1238 * device lacks the ability to confirm a pairing request. If set
1239 * to non-NULL the cancel callback must also be provided, since
1240 * this is the only way the application can find out that it should
1241 * stop requesting the user to confirm a pairing request.
1242 *
1243 * @param conn Connection where pairing is currently active.
1244 */
1245 void (*pairing_confirm)(struct bt_conn *conn);
1246
1247 #if defined(CONFIG_BT_BREDR)
1248 /** @brief Request the user to enter a passkey.
1249 *
1250 * This callback will be called for a BR/EDR (Bluetooth Classic)
1251 * connection where pairing is being performed. Once called the
1252 * user is expected to enter a PIN code with a length between
1253 * 1 and 16 digits. If the @a highsec parameter is set to true
1254 * the PIN code must be 16 digits long.
1255 *
1256 * Once entered, the PIN code should be given to the stack using
1257 * the bt_conn_auth_pincode_entry() API.
1258 *
1259 * This callback may be set to NULL, however in that case pairing
1260 * over BR/EDR will not be possible. If provided, the cancel
1261 * callback must be provided as well.
1262 *
1263 * @param conn Connection where pairing is currently active.
1264 * @param highsec true if 16 digit PIN is required.
1265 */
1266 void (*pincode_entry)(struct bt_conn *conn, bool highsec);
1267 #endif
1268
1269 /** @brief notify that pairing process was complete.
1270 *
1271 * This callback notifies the application that the pairing process
1272 * has been completed.
1273 *
1274 * @param conn Connection object.
1275 * @param bonded pairing is bonded or not.
1276 */
1277 void (*pairing_complete)(struct bt_conn *conn, bool bonded);
1278
1279 /** @brief notify that pairing process has failed.
1280 *
1281 * @param conn Connection object.
1282 * @param reason Pairing failed reason
1283 */
1284 void (*pairing_failed)(struct bt_conn *conn,
1285 enum bt_security_err reason);
1286 };
1287
1288 /** @brief Register authentication callbacks.
1289 *
1290 * Register callbacks to handle authenticated pairing. Passing NULL
1291 * unregisters a previous callbacks structure.
1292 *
1293 * @param cb Callback struct.
1294 *
1295 * @return Zero on success or negative error code otherwise
1296 */
1297 int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb);
1298
1299 /** @brief Reply with entered passkey.
1300 *
1301 * This function should be called only after passkey_entry callback from
1302 * bt_conn_auth_cb structure was called.
1303 *
1304 * @param conn Connection object.
1305 * @param passkey Entered passkey.
1306 *
1307 * @return Zero on success or negative error code otherwise
1308 */
1309 int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey);
1310
1311 /** @brief Cancel ongoing authenticated pairing.
1312 *
1313 * This function allows to cancel ongoing authenticated pairing.
1314 *
1315 * @param conn Connection object.
1316 *
1317 * @return Zero on success or negative error code otherwise
1318 */
1319 int bt_conn_auth_cancel(struct bt_conn *conn);
1320
1321 /** @brief Reply if passkey was confirmed to match by user.
1322 *
1323 * This function should be called only after passkey_confirm callback from
1324 * bt_conn_auth_cb structure was called.
1325 *
1326 * @param conn Connection object.
1327 *
1328 * @return Zero on success or negative error code otherwise
1329 */
1330 int bt_conn_auth_passkey_confirm(struct bt_conn *conn);
1331
1332 /** @brief Reply if incoming pairing was confirmed by user.
1333 *
1334 * This function should be called only after pairing_confirm callback from
1335 * bt_conn_auth_cb structure was called if user confirmed incoming pairing.
1336 *
1337 * @param conn Connection object.
1338 *
1339 * @return Zero on success or negative error code otherwise
1340 */
1341 int bt_conn_auth_pairing_confirm(struct bt_conn *conn);
1342
1343 /** @brief Reply with entered PIN code.
1344 *
1345 * This function should be called only after PIN code callback from
1346 * bt_conn_auth_cb structure was called. It's for legacy 2.0 devices.
1347 *
1348 * @param conn Connection object.
1349 * @param pin Entered PIN code.
1350 *
1351 * @return Zero on success or negative error code otherwise
1352 */
1353 int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin);
1354
1355 /** Connection parameters for BR/EDR connections */
1356 struct bt_br_conn_param {
1357 bool allow_role_switch;
1358 };
1359
1360 /** @brief Initialize BR/EDR connection parameters
1361 *
1362 * @param role_switch True if role switch is allowed
1363 */
1364 #define BT_BR_CONN_PARAM_INIT(role_switch) \
1365 { \
1366 .allow_role_switch = (role_switch), \
1367 }
1368
1369 /** Helper to declare BR/EDR connection parameters inline
1370 *
1371 * @param role_switch True if role switch is allowed
1372 */
1373 #define BT_BR_CONN_PARAM(role_switch) \
1374 ((struct bt_br_conn_param[]) { \
1375 BT_BR_CONN_PARAM_INIT(role_switch) \
1376 })
1377
1378 /** Default BR/EDR connection parameters:
1379 * Role switch allowed
1380 */
1381 #define BT_BR_CONN_PARAM_DEFAULT BT_BR_CONN_PARAM(true)
1382
1383
1384 /** @brief Initiate an BR/EDR connection to a remote device.
1385 *
1386 * Allows initiate new BR/EDR link to remote peer using its address.
1387 *
1388 * The caller gets a new reference to the connection object which must be
1389 * released with bt_conn_unref() once done using the object.
1390 *
1391 * @param peer Remote address.
1392 * @param param Initial connection parameters.
1393 *
1394 * @return Valid connection object on success or NULL otherwise.
1395 */
1396 struct bt_conn *bt_conn_create_br(const bt_addr_t *peer,
1397 const struct bt_br_conn_param *param);
1398
1399 /** @brief Initiate an SCO connection to a remote device.
1400 *
1401 * Allows initiate new SCO link to remote peer using its address.
1402 *
1403 * The caller gets a new reference to the connection object which must be
1404 * released with bt_conn_unref() once done using the object.
1405 *
1406 * @param peer Remote address.
1407 *
1408 * @return Valid connection object on success or NULL otherwise.
1409 */
1410 struct bt_conn *bt_conn_create_sco(const bt_addr_t *peer);
1411
1412 #ifdef __cplusplus
1413 }
1414 #endif
1415
1416 /**
1417 * @}
1418 */
1419
1420 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_ */
1421