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