Line data Source code
1 1 : /*
2 : * Copyright (c) 2023 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief API for controlling generic network association routines on network devices that
10 : * support it.
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_CONN_MGR_CONNECTIVITY_H_
14 : #define ZEPHYR_INCLUDE_CONN_MGR_CONNECTIVITY_H_
15 :
16 : #include <zephyr/device.h>
17 : #include <zephyr/net/net_if.h>
18 : #include <zephyr/sys/iterable_sections.h>
19 : #include <zephyr/net/net_mgmt.h>
20 :
21 : #ifdef __cplusplus
22 : extern "C" {
23 : #endif
24 :
25 : /**
26 : * @brief Connection Manager Connectivity API
27 : * @defgroup conn_mgr_connectivity Connection Manager Connectivity API
28 : * @since 3.4
29 : * @version 0.8.0
30 : * @ingroup networking
31 : * @{
32 : */
33 :
34 :
35 : /** @cond INTERNAL_HIDDEN */
36 :
37 : /* Connectivity Events */
38 : #define NET_MGMT_CONN_LAYER NET_MGMT_LAYER(NET_MGMT_LAYER_L2)
39 : #define NET_MGMT_CONN_CODE NET_MGMT_LAYER_CODE(NET_MGMT_LAYER_CODE_CONN)
40 : #define NET_MGMT_CONN_BASE (NET_MGMT_CONN_LAYER | NET_MGMT_CONN_CODE | \
41 : NET_MGMT_EVENT_BIT)
42 : #define NET_MGMT_CONN_IF_EVENT (NET_MGMT_IFACE_BIT | NET_MGMT_CONN_BASE)
43 :
44 : enum {
45 : NET_EVENT_CONN_CMD_IF_TIMEOUT_VAL,
46 : NET_EVENT_CONN_CMD_IF_FATAL_ERROR_VAL,
47 :
48 : NET_EVENT_CONN_CMD_MAX
49 : };
50 :
51 : BUILD_ASSERT(NET_EVENT_CONN_CMD_MAX <= NET_MGMT_MAX_COMMANDS,
52 : "Number of events in net_event_conn_cmd exceeds the limit");
53 :
54 : enum net_event_conn_cmd {
55 : NET_MGMT_CMD(NET_EVENT_CONN_CMD_IF_TIMEOUT),
56 : NET_MGMT_CMD(NET_EVENT_CONN_CMD_IF_FATAL_ERROR),
57 : };
58 :
59 : /** @endcond */
60 :
61 : /**
62 : * @brief net_mgmt event raised when a connection attempt times out
63 : */
64 1 : #define NET_EVENT_CONN_IF_TIMEOUT \
65 : (NET_MGMT_CONN_IF_EVENT | NET_EVENT_CONN_CMD_IF_TIMEOUT)
66 :
67 : /**
68 : * @brief net_mgmt event raised when a non-recoverable connectivity error occurs on an iface
69 : */
70 1 : #define NET_EVENT_CONN_IF_FATAL_ERROR \
71 : (NET_MGMT_CONN_IF_EVENT | NET_EVENT_CONN_CMD_IF_FATAL_ERROR)
72 :
73 :
74 : /**
75 : * @brief Per-iface connectivity flags
76 : */
77 1 : enum conn_mgr_if_flag {
78 : /**
79 : * Persistent
80 : *
81 : * When set, indicates that the connectivity implementation bound to this iface should
82 : * attempt to persist connectivity by automatically reconnecting after connection loss.
83 : */
84 : CONN_MGR_IF_PERSISTENT,
85 :
86 : /**
87 : * No auto-connect
88 : *
89 : * When set, conn_mgr will not automatically attempt to connect this iface when it reaches
90 : * admin-up.
91 : */
92 : CONN_MGR_IF_NO_AUTO_CONNECT,
93 :
94 : /**
95 : * No auto-down
96 : *
97 : * When set, conn_mgr will not automatically take the iface admin-down when it stops
98 : * trying to connect, even if CONFIG_NET_CONNECTION_MANAGER_AUTO_IF_DOWN is enabled.
99 : */
100 : CONN_MGR_IF_NO_AUTO_DOWN,
101 :
102 : /** @cond INTERNAL_HIDDEN */
103 : /**
104 : * Internal flag indicating that the interface is in active (application initiated)
105 : * disconnect.
106 : */
107 : CONN_MGR_IF_DISCONNECTING,
108 :
109 : /* Total number of flags - must be at the end of the enum */
110 : CONN_MGR_NUM_IF_FLAGS,
111 : /** @endcond */
112 : };
113 :
114 : /** Value to use with @ref conn_mgr_if_set_timeout and @ref conn_mgr_conn_binding.timeout to
115 : * indicate no timeout
116 : */
117 1 : #define CONN_MGR_IF_NO_TIMEOUT 0
118 :
119 : /**
120 : * @brief Connect interface
121 : *
122 : * If the provided iface has been bound to a connectivity implementation, initiate
123 : * network connect/association.
124 : *
125 : * Automatically takes the iface admin-up (by calling @ref net_if_up) if it isn't already.
126 : *
127 : * Non-Blocking.
128 : *
129 : * @param iface Pointer to network interface
130 : * @retval 0 on success.
131 : * @retval -ESHUTDOWN if the iface is not admin-up.
132 : * @retval -ENOTSUP if the iface does not have a connectivity implementation.
133 : * @retval implementation-specific status code otherwise.
134 : */
135 1 : int conn_mgr_if_connect(struct net_if *iface);
136 :
137 : /**
138 : * @brief Disconnect interface
139 : *
140 : * If the provided iface has been bound to a connectivity implementation, disconnect/disassociate
141 : * it from the network, and cancel any pending attempts to connect/associate.
142 : *
143 : * Does nothing if the iface is currently admin-down.
144 : *
145 : * @param iface Pointer to network interface
146 : *
147 : * @retval 0 on success.
148 : * @retval -ENOTSUP if the iface does not have a connectivity implementation.
149 : * @retval implementation-specific status code otherwise.
150 : */
151 1 : int conn_mgr_if_disconnect(struct net_if *iface);
152 :
153 : /**
154 : * @brief Check whether the provided network interface supports connectivity / has been bound
155 : * to a connectivity implementation.
156 : *
157 : * @param iface Pointer to the iface to check.
158 : * @retval true if connectivity is supported (a connectivity implementation has been bound).
159 : * @retval false otherwise.
160 : */
161 1 : bool conn_mgr_if_is_bound(struct net_if *iface);
162 :
163 : /**
164 : * @brief Set implementation-specific connectivity options.
165 : *
166 : * If the provided iface has been bound to a connectivity implementation that supports it,
167 : * implementation-specific connectivity options related to the iface.
168 : *
169 : * @param iface Pointer to the network interface.
170 : * @param optname Integer value representing the option to set.
171 : * The meaning of values is up to the conn_mgr_conn_api implementation.
172 : * Some settings may affect multiple ifaces.
173 : * @param optval Pointer to the value to be assigned to the option.
174 : * @param optlen Length (in bytes) of the value to be assigned to the option.
175 : * @retval 0 if successful.
176 : * @retval -ENOTSUP if conn_mgr_if_set_opt not implemented by the iface.
177 : * @retval -ENOBUFS if optlen is too long.
178 : * @retval -EINVAL if NULL optval pointer provided.
179 : * @retval -ENOPROTOOPT if the optname is not recognized.
180 : * @retval implementation-specific error code otherwise.
181 : */
182 1 : int conn_mgr_if_set_opt(struct net_if *iface, int optname, const void *optval, size_t optlen);
183 :
184 : /**
185 : * @brief Get implementation-specific connectivity options.
186 : *
187 : * If the provided iface has been bound to a connectivity implementation that supports it,
188 : * retrieves implementation-specific connectivity options related to the iface.
189 : *
190 : * @param iface Pointer to the network interface.
191 : * @param optname Integer value representing the option to set.
192 : * The meaning of values is up to the conn_mgr_conn_api implementation.
193 : * Some settings may be shared by multiple ifaces.
194 : * @param optval Pointer to where the retrieved value should be stored.
195 : * @param optlen Pointer to length (in bytes) of the destination buffer available for storing the
196 : * retrieved value. If the available space is less than what is needed, -ENOBUFS
197 : * is returned. If the available space is invalid, -EINVAL is returned.
198 : *
199 : * optlen will always be set to the total number of bytes written, regardless of
200 : * whether an error is returned, even if zero bytes were written.
201 : *
202 : * @retval 0 if successful.
203 : * @retval -ENOTSUP if conn_mgr_if_get_opt is not implemented by the iface.
204 : * @retval -ENOBUFS if retrieval buffer is too small.
205 : * @retval -EINVAL if invalid retrieval buffer length is provided, or if NULL optval or
206 : * optlen pointer provided.
207 : * @retval -ENOPROTOOPT if the optname is not recognized.
208 : * @retval implementation-specific error code otherwise.
209 : */
210 1 : int conn_mgr_if_get_opt(struct net_if *iface, int optname, void *optval, size_t *optlen);
211 :
212 : /**
213 : * @brief Check the value of connectivity flags
214 : *
215 : * If the provided iface is bound to a connectivity implementation, retrieves the value of the
216 : * specified connectivity flag associated with that iface.
217 : *
218 : * @param iface - Pointer to the network interface to check.
219 : * @param flag - The flag to check.
220 : * @return True if the flag is set, otherwise False.
221 : * Also returns False if the provided iface is not bound to a connectivity implementation,
222 : * or the requested flag doesn't exist.
223 : */
224 1 : bool conn_mgr_if_get_flag(struct net_if *iface, enum conn_mgr_if_flag flag);
225 :
226 : /**
227 : * @brief Set the value of a connectivity flags
228 : *
229 : * If the provided iface is bound to a connectivity implementation, sets the value of the
230 : * specified connectivity flag associated with that iface.
231 : *
232 : * @param iface - Pointer to the network interface to modify.
233 : * @param flag - The flag to set.
234 : * @param value - Whether the flag should be enabled or disabled.
235 : * @retval 0 on success.
236 : * @retval -EINVAL if the flag does not exist.
237 : * @retval -ENOTSUP if the provided iface is not bound to a connectivity implementation.
238 : */
239 1 : int conn_mgr_if_set_flag(struct net_if *iface, enum conn_mgr_if_flag flag, bool value);
240 :
241 : /**
242 : * @brief Get the connectivity timeout for an iface
243 : *
244 : * If the provided iface is bound to a connectivity implementation, retrieves the timeout setting
245 : * in seconds for it.
246 : *
247 : * @param iface - Pointer to the iface to check.
248 : * @return int - The connectivity timeout value (in seconds) if it could be retrieved, otherwise
249 : * CONN_MGR_IF_NO_TIMEOUT.
250 : */
251 1 : int conn_mgr_if_get_timeout(struct net_if *iface);
252 :
253 : /**
254 : * @brief Set the connectivity timeout for an iface.
255 : *
256 : * If the provided iface is bound to a connectivity implementation, sets the timeout setting in
257 : * seconds for it.
258 : *
259 : * @param iface - Pointer to the network interface to modify.
260 : * @param timeout - The timeout value to set (in seconds).
261 : * Pass @ref CONN_MGR_IF_NO_TIMEOUT to disable the timeout.
262 : * @retval 0 on success.
263 : * @retval -ENOTSUP if the provided iface is not bound to a connectivity implementation.
264 : */
265 1 : int conn_mgr_if_set_timeout(struct net_if *iface, int timeout);
266 :
267 : /**
268 : * @}
269 : */
270 :
271 : /**
272 : * @brief Connection Manager Bulk API
273 : * @defgroup conn_mgr_connectivity_bulk Connection Manager Connectivity Bulk API
274 : * @since 3.4
275 : * @version 0.1.0
276 : * @ingroup conn_mgr_connectivity
277 : * @{
278 : */
279 :
280 : /**
281 : * @brief Convenience function that takes all available ifaces into the admin-up state.
282 : *
283 : * Essentially a wrapper for @ref net_if_up.
284 : *
285 : * @param skip_ignored - If true, only affect ifaces that aren't ignored by conn_mgr.
286 : * Otherwise, affect all ifaces.
287 : * @return 0 if all net_if_up calls returned 0, otherwise the first nonzero value
288 : * returned by a net_if_up call.
289 : */
290 1 : int conn_mgr_all_if_up(bool skip_ignored);
291 :
292 :
293 : /**
294 : * @brief Convenience function that takes all available ifaces into the admin-down state.
295 : *
296 : * Essentially a wrapper for @ref net_if_down.
297 : *
298 : * @param skip_ignored - If true, only affect ifaces that aren't ignored by conn_mgr.
299 : * Otherwise, affect all ifaces.
300 : * @return 0 if all net_if_down calls returned 0, otherwise the first nonzero value
301 : * returned by a net_if_down call.
302 : */
303 1 : int conn_mgr_all_if_down(bool skip_ignored);
304 :
305 : /**
306 : * @brief Convenience function that takes all available ifaces into the admin-up state, and
307 : * connects those that support connectivity.
308 : *
309 : * Essentially a wrapper for @ref net_if_up and @ref conn_mgr_if_connect.
310 : *
311 : * @param skip_ignored - If true, only affect ifaces that aren't ignored by conn_mgr.
312 : * Otherwise, affect all ifaces.
313 : * @return 0 if all net_if_up and conn_mgr_if_connect calls returned 0, otherwise the first nonzero
314 : * value returned by either net_if_up or conn_mgr_if_connect.
315 : */
316 1 : int conn_mgr_all_if_connect(bool skip_ignored);
317 :
318 : /**
319 : * @brief Convenience function that disconnects all available ifaces that support connectivity
320 : * without putting them into admin-down state (unless auto-down is enabled for the iface).
321 : *
322 : * Essentially a wrapper for @ref net_if_down.
323 : *
324 : * @param skip_ignored - If true, only affect ifaces that aren't ignored by conn_mgr.
325 : * Otherwise, affect all ifaces.
326 : * @return 0 if all net_if_up and conn_mgr_if_connect calls returned 0, otherwise the first nonzero
327 : * value returned by either net_if_up or conn_mgr_if_connect.
328 : */
329 1 : int conn_mgr_all_if_disconnect(bool skip_ignored);
330 :
331 : /**
332 : * @}
333 : */
334 :
335 : #ifdef __cplusplus
336 : }
337 : #endif
338 :
339 : #endif /* ZEPHYR_INCLUDE_CONN_MGR_CONNECTIVITY_H_ */
|
