1 /* Copyright (c) 2023 Nordic Semiconductor ASA 2 * SPDX-License-Identifier: Apache-2.0 3 */ 4 5 #ifndef ZEPHYR_TESTS_BLUETOOTH_COMMON_TESTLIB_INCLUDE_TESTLIB_CONN_H_ 6 #define ZEPHYR_TESTS_BLUETOOTH_COMMON_TESTLIB_INCLUDE_TESTLIB_CONN_H_ 7 8 #include <stdint.h> 9 #include <zephyr/bluetooth/addr.h> 10 #include <zephyr/bluetooth/conn.h> 11 12 /** 13 * @brief Scan and connect using address 14 * 15 * Synchronous: Blocks until the connection procedure completes. 16 * Thread-safe: 17 * 18 * This is a synchronous wrapper around @ref bt_conn_le_create with 19 * default params. It will wait until the @ref bt_conn_cb.connected 20 * event and return the HCI status of the connection creation. 21 * 22 * The reference created by @ref bt_conn_le_create is put in @p connp. 23 * 24 * @note The connection reference presists if the connection procedure 25 * fails at a later point. @p connp is a reified reference: if it's not 26 * NULL, then it's a valid reference. 27 * 28 * @remark Not disposing of the connection reference in the case of 29 * connection failure is intentional. It's useful for comparing against 30 * raw @ref bt_conn_cb.connected events. 31 * 32 * @note The reference variable @p connp is required be empty (i.e. 33 * NULL) on entry. 34 * 35 * @param peer Peer address. 36 * @param[out] conn Connection reference variable. 37 * 38 * @retval 0 Connection was enstablished. 39 * @retval -errno @ref bt_conn_le_create error. No connection object 40 * reference was created. 41 * @retval BT_HCI_ERR HCI reason for connection failure. A connection 42 * object reference was created and put in @p connp. 43 * 44 */ 45 int bt_testlib_connect(const bt_addr_le_t *peer, struct bt_conn **connp); 46 47 /** 48 * @brief Disconnect, wait and dispose of reference. 49 * 50 * The disconnect reason for a normal disconnect should be @ref 51 * BT_HCI_ERR_REMOTE_USER_TERM_CONN. 52 * 53 * The following disconnect reasons are allowed: 54 * 55 * - @ref BT_HCI_ERR_AUTH_FAIL 56 * - @ref BT_HCI_ERR_REMOTE_USER_TERM_CONN 57 * - @ref BT_HCI_ERR_REMOTE_LOW_RESOURCES 58 * - @ref BT_HCI_ERR_REMOTE_POWER_OFF 59 * - @ref BT_HCI_ERR_UNSUPP_REMOTE_FEATURE 60 * - @ref BT_HCI_ERR_PAIRING_NOT_SUPPORTED 61 * - @ref BT_HCI_ERR_UNACCEPT_CONN_PARAM 62 */ 63 int bt_testlib_disconnect(struct bt_conn **connp, uint8_t reason); 64 65 /** 66 * @brief Wait for connected state 67 * 68 * Thread-safe. 69 * 70 * @attention This function does not look at the history of a connection 71 * object. If it's already disconnected after a connection, then this 72 * function will wait forever. Don't use this function if you cannot 73 * guarantee that any disconnection event comes after this function is 74 * called. This is only truly safe in a simulated environment. 75 */ 76 int bt_testlib_wait_connected(struct bt_conn *conn); 77 78 /** 79 * @brief Wait for disconnected state 80 * 81 * Thread-safe. 82 */ 83 int bt_testlib_wait_disconnected(struct bt_conn *conn); 84 85 /** 86 * @brief Dispose of a reified connection reference 87 * 88 * Thread-safe. 89 * 90 * Atomically swaps NULL into the reference variable @p connp, then 91 * moves the reference into @ref bt_conn_unref. 92 */ 93 void bt_testlib_conn_unref(struct bt_conn **connp); 94 95 /** @brief Obtain a reference to a connection object by its 96 * index 97 * 98 * This is an inverse of @ref bt_conn_index during the lifetime 99 * of the original @ref bt_conn reference. 100 * 101 * This function can be used instead of @ref bt_conn_foreach to 102 * loop over all connections. 103 * 104 * @note The ranges of conn_index overlap for different 105 * connection types. They all range from 0 up to their 106 * respective capacities, tabulated below. 107 * 108 * @p conn_type | Capacity 109 * ------------------|------------------------ 110 * BT_CONN_TYPE_LE | CONFIG_BT_MAX_CONN 111 * BT_CONN_TYPE_SCO | CONFIG_BT_MAX_SCO_CONN 112 * BT_CONN_TYPE_ISO | CONFIG_BT_ISO_MAX_CHAN 113 * 114 * Internal details that cannot be relied on: 115 * - The memory addresses returned point into an array. 116 * - The same index and type always yields the same memory 117 * address. 118 * 119 * Guarantees: 120 * - Looping over the whole range is equivalent to @ref 121 * bt_conn_foreach. 122 * 123 * @retval NULL if the reference is dead 124 * @retval conn a reference to the found connection object 125 */ 126 struct bt_conn *bt_testlib_conn_unindex(enum bt_conn_type conn_type, uint8_t conn_index); 127 128 /** 129 * @brief Wait until there is a free connection slot 130 * 131 * Thread-safe. 132 * 133 * Returns when there already is a free connection slot or a 134 * connection slot is recycled. 135 * 136 * @note The free connection slots may have been taken by the 137 * time this function returns. Call this function in a loop if 138 * needed. 139 */ 140 void bt_testlib_conn_wait_free(void); 141 142 #endif /* ZEPHYR_TESTS_BLUETOOTH_COMMON_TESTLIB_INCLUDE_TESTLIB_CONN_H_ */ 143