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 : NET_EVENT_CONN_CMD_IF_IDLE_TIMEOUT_VAL,
48 :
49 : NET_EVENT_CONN_CMD_MAX
50 : };
51 :
52 : BUILD_ASSERT(NET_EVENT_CONN_CMD_MAX <= NET_MGMT_MAX_COMMANDS,
53 : "Number of events in net_event_conn_cmd exceeds the limit");
54 :
55 : enum net_event_conn_cmd {
56 : NET_MGMT_CMD(NET_EVENT_CONN_CMD_IF_TIMEOUT),
57 : NET_MGMT_CMD(NET_EVENT_CONN_CMD_IF_FATAL_ERROR),
58 : NET_MGMT_CMD(NET_EVENT_CONN_CMD_IF_IDLE_TIMEOUT),
59 : };
60 :
61 : /** @endcond */
62 :
63 : /**
64 : * @brief net_mgmt event raised when a connection attempt times out
65 : */
66 1 : #define NET_EVENT_CONN_IF_TIMEOUT \
67 : (NET_MGMT_CONN_IF_EVENT | NET_EVENT_CONN_CMD_IF_TIMEOUT)
68 :
69 : /**
70 : * @brief net_mgmt event raised when a non-recoverable connectivity error occurs on an iface
71 : */
72 1 : #define NET_EVENT_CONN_IF_FATAL_ERROR \
73 : (NET_MGMT_CONN_IF_EVENT | NET_EVENT_CONN_CMD_IF_FATAL_ERROR)
74 :
75 : /**
76 : * @brief net_mgmt event raised when an interface times out due to inactivity
77 : */
78 1 : #define NET_EVENT_CONN_IF_IDLE_TIMEOUT \
79 : (NET_MGMT_CONN_IF_EVENT | NET_EVENT_CONN_CMD_IF_IDLE_TIMEOUT)
80 :
81 :
82 : /**
83 : * @brief Per-iface connectivity flags
84 : */
85 1 : enum conn_mgr_if_flag {
86 : /**
87 : * Persistent
88 : *
89 : * When set, indicates that the connectivity implementation bound to this iface should
90 : * attempt to persist connectivity by automatically reconnecting after connection loss.
91 : */
92 : CONN_MGR_IF_PERSISTENT,
93 :
94 : /**
95 : * No auto-connect
96 : *
97 : * When set, conn_mgr will not automatically attempt to connect this iface when it reaches
98 : * admin-up.
99 : */
100 : CONN_MGR_IF_NO_AUTO_CONNECT,
101 :
102 : /**
103 : * No auto-down
104 : *
105 : * When set, conn_mgr will not automatically take the iface admin-down when it stops
106 : * trying to connect, even if CONFIG_NET_CONNECTION_MANAGER_AUTO_IF_DOWN is enabled.
107 : */
108 : CONN_MGR_IF_NO_AUTO_DOWN,
109 :
110 : /** @cond INTERNAL_HIDDEN */
111 : /**
112 : * Internal flag indicating that the interface is in active (application initiated)
113 : * disconnect.
114 : */
115 : CONN_MGR_IF_DISCONNECTING,
116 :
117 : /* Total number of flags - must be at the end of the enum */
118 : CONN_MGR_NUM_IF_FLAGS,
119 : /** @endcond */
120 : };
121 :
122 : /** Value to use with @ref conn_mgr_if_set_timeout and @ref conn_mgr_conn_binding.timeout to
123 : * indicate no timeout
124 : */
125 1 : #define CONN_MGR_IF_NO_TIMEOUT 0
126 :
127 : /**
128 : * @brief Connect interface
129 : *
130 : * If the provided iface has been bound to a connectivity implementation, initiate
131 : * network connect/association.
132 : *
133 : * Automatically takes the iface admin-up (by calling @ref net_if_up) if it isn't already.
134 : *
135 : * Non-Blocking.
136 : *
137 : * @param iface Pointer to network interface
138 : * @retval 0 on success.
139 : * @retval -ESHUTDOWN if the iface is not admin-up.
140 : * @retval -ENOTSUP if the iface does not have a connectivity implementation.
141 : * @retval implementation-specific status code otherwise.
142 : */
143 1 : int conn_mgr_if_connect(struct net_if *iface);
144 :
145 : /**
146 : * @brief Disconnect interface
147 : *
148 : * If the provided iface has been bound to a connectivity implementation, disconnect/disassociate
149 : * it from the network, and cancel any pending attempts to connect/associate.
150 : *
151 : * Does nothing if the iface is currently admin-down.
152 : *
153 : * @param iface Pointer to network interface
154 : *
155 : * @retval 0 on success.
156 : * @retval -ENOTSUP if the iface does not have a connectivity implementation.
157 : * @retval implementation-specific status code otherwise.
158 : */
159 1 : int conn_mgr_if_disconnect(struct net_if *iface);
160 :
161 : /**
162 : * @brief Check whether the provided network interface supports connectivity / has been bound
163 : * to a connectivity implementation.
164 : *
165 : * @param iface Pointer to the iface to check.
166 : * @retval true if connectivity is supported (a connectivity implementation has been bound).
167 : * @retval false otherwise.
168 : */
169 1 : bool conn_mgr_if_is_bound(struct net_if *iface);
170 :
171 : /**
172 : * @brief Set implementation-specific connectivity options.
173 : *
174 : * If the provided iface has been bound to a connectivity implementation that supports it,
175 : * implementation-specific connectivity options related to the iface.
176 : *
177 : * @param iface Pointer to the network interface.
178 : * @param optname Integer value representing the option to set.
179 : * The meaning of values is up to the conn_mgr_conn_api implementation.
180 : * Some settings may affect multiple ifaces.
181 : * @param optval Pointer to the value to be assigned to the option.
182 : * @param optlen Length (in bytes) of the value to be assigned to the option.
183 : * @retval 0 if successful.
184 : * @retval -ENOTSUP if conn_mgr_if_set_opt not implemented by the iface.
185 : * @retval -ENOBUFS if optlen is too long.
186 : * @retval -EINVAL if NULL optval pointer provided.
187 : * @retval -ENOPROTOOPT if the optname is not recognized.
188 : * @retval implementation-specific error code otherwise.
189 : */
190 1 : int conn_mgr_if_set_opt(struct net_if *iface, int optname, const void *optval, size_t optlen);
191 :
192 : /**
193 : * @brief Get implementation-specific connectivity options.
194 : *
195 : * If the provided iface has been bound to a connectivity implementation that supports it,
196 : * retrieves implementation-specific connectivity options related to the iface.
197 : *
198 : * @param iface Pointer to the network interface.
199 : * @param optname Integer value representing the option to set.
200 : * The meaning of values is up to the conn_mgr_conn_api implementation.
201 : * Some settings may be shared by multiple ifaces.
202 : * @param optval Pointer to where the retrieved value should be stored.
203 : * @param optlen Pointer to length (in bytes) of the destination buffer available for storing the
204 : * retrieved value. If the available space is less than what is needed, -ENOBUFS
205 : * is returned. If the available space is invalid, -EINVAL is returned.
206 : *
207 : * optlen will always be set to the total number of bytes written, regardless of
208 : * whether an error is returned, even if zero bytes were written.
209 : *
210 : * @retval 0 if successful.
211 : * @retval -ENOTSUP if conn_mgr_if_get_opt is not implemented by the iface.
212 : * @retval -ENOBUFS if retrieval buffer is too small.
213 : * @retval -EINVAL if invalid retrieval buffer length is provided, or if NULL optval or
214 : * optlen pointer provided.
215 : * @retval -ENOPROTOOPT if the optname is not recognized.
216 : * @retval implementation-specific error code otherwise.
217 : */
218 1 : int conn_mgr_if_get_opt(struct net_if *iface, int optname, void *optval, size_t *optlen);
219 :
220 : /**
221 : * @brief Check the value of connectivity flags
222 : *
223 : * If the provided iface is bound to a connectivity implementation, retrieves the value of the
224 : * specified connectivity flag associated with that iface.
225 : *
226 : * @param iface - Pointer to the network interface to check.
227 : * @param flag - The flag to check.
228 : * @return True if the flag is set, otherwise False.
229 : * Also returns False if the provided iface is not bound to a connectivity implementation,
230 : * or the requested flag doesn't exist.
231 : */
232 1 : bool conn_mgr_if_get_flag(struct net_if *iface, enum conn_mgr_if_flag flag);
233 :
234 : /**
235 : * @brief Set the value of a connectivity flags
236 : *
237 : * If the provided iface is bound to a connectivity implementation, sets the value of the
238 : * specified connectivity flag associated with that iface.
239 : *
240 : * @param iface - Pointer to the network interface to modify.
241 : * @param flag - The flag to set.
242 : * @param value - Whether the flag should be enabled or disabled.
243 : * @retval 0 on success.
244 : * @retval -EINVAL if the flag does not exist.
245 : * @retval -ENOTSUP if the provided iface is not bound to a connectivity implementation.
246 : */
247 1 : int conn_mgr_if_set_flag(struct net_if *iface, enum conn_mgr_if_flag flag, bool value);
248 :
249 : /**
250 : * @brief Get the connectivity timeout for an iface
251 : *
252 : * If the provided iface is bound to a connectivity implementation, retrieves the timeout setting
253 : * in seconds for it.
254 : *
255 : * @param iface - Pointer to the iface to check.
256 : * @return int - The connectivity timeout value (in seconds) if it could be retrieved, otherwise
257 : * CONN_MGR_IF_NO_TIMEOUT.
258 : */
259 1 : int conn_mgr_if_get_timeout(struct net_if *iface);
260 :
261 : /**
262 : * @brief Set the connectivity timeout for an iface.
263 : *
264 : * If the provided iface is bound to a connectivity implementation, sets the timeout setting in
265 : * seconds for it.
266 : *
267 : * @param iface - Pointer to the network interface to modify.
268 : * @param timeout - The timeout value to set (in seconds).
269 : * Pass @ref CONN_MGR_IF_NO_TIMEOUT to disable the timeout.
270 : * @retval 0 on success.
271 : * @retval -ENOTSUP if the provided iface is not bound to a connectivity implementation.
272 : */
273 1 : int conn_mgr_if_set_timeout(struct net_if *iface, int timeout);
274 :
275 : /**
276 : * @brief Get the idle timeout for an iface
277 : *
278 : * If the provided iface is bound to a connectivity implementation, retrieves the idle timeout
279 : * setting in seconds for it.
280 : *
281 : * @param iface - Pointer to the iface to check.
282 : * @return int - The connectivity timeout value (in seconds) if it could be retrieved, otherwise
283 : * CONN_MGR_IF_NO_TIMEOUT.
284 : */
285 1 : int conn_mgr_if_get_idle_timeout(struct net_if *iface);
286 :
287 : /**
288 : * @brief Set the idle timeout for an iface.
289 : *
290 : * If the provided iface is bound to a connectivity implementation, sets the idle timeout setting
291 : * in seconds for it.
292 : *
293 : * @param iface - Pointer to the network interface to modify.
294 : * @param timeout - The timeout value to set (in seconds).
295 : * Pass @ref CONN_MGR_IF_NO_TIMEOUT to disable the timeout.
296 : * @retval 0 on success.
297 : * @retval -ENOTSUP if the provided iface is not bound to a connectivity implementation.
298 : */
299 1 : int conn_mgr_if_set_idle_timeout(struct net_if *iface, int timeout);
300 :
301 : #if defined(CONFIG_NET_CONNECTION_MANAGER) || defined(__DOXYGEN__)
302 : /**
303 : * @brief Notify connection manager that interface was just used
304 : *
305 : * @note Typically called from network drivers, not application software.
306 : *
307 : * @param iface iface that was just used
308 : */
309 1 : void conn_mgr_if_used(struct net_if *iface);
310 : #else
311 : #define conn_mgr_if_used(iface) (void)(iface)
312 : #endif /* defined(CONFIG_NET_CONNECTION_MANAGER) || defined(__DOXYGEN__) */
313 :
314 : /**
315 : * @}
316 : */
317 :
318 : /**
319 : * @brief Connection Manager Bulk API
320 : * @defgroup conn_mgr_connectivity_bulk Connection Manager Connectivity Bulk API
321 : * @since 3.4
322 : * @version 0.1.0
323 : * @ingroup conn_mgr_connectivity
324 : * @{
325 : */
326 :
327 : /**
328 : * @brief Convenience function that takes all available ifaces into the admin-up state.
329 : *
330 : * Essentially a wrapper for @ref net_if_up.
331 : *
332 : * @param skip_ignored - If true, only affect ifaces that aren't ignored by conn_mgr.
333 : * Otherwise, affect all ifaces.
334 : * @return 0 if all net_if_up calls returned 0, otherwise the first nonzero value
335 : * returned by a net_if_up call.
336 : */
337 1 : int conn_mgr_all_if_up(bool skip_ignored);
338 :
339 :
340 : /**
341 : * @brief Convenience function that takes all available ifaces into the admin-down state.
342 : *
343 : * Essentially a wrapper for @ref net_if_down.
344 : *
345 : * @param skip_ignored - If true, only affect ifaces that aren't ignored by conn_mgr.
346 : * Otherwise, affect all ifaces.
347 : * @return 0 if all net_if_down calls returned 0, otherwise the first nonzero value
348 : * returned by a net_if_down call.
349 : */
350 1 : int conn_mgr_all_if_down(bool skip_ignored);
351 :
352 : /**
353 : * @brief Convenience function that takes all available ifaces into the admin-up state, and
354 : * connects those that support connectivity.
355 : *
356 : * Essentially a wrapper for @ref net_if_up and @ref conn_mgr_if_connect.
357 : *
358 : * @param skip_ignored - If true, only affect ifaces that aren't ignored by conn_mgr.
359 : * Otherwise, affect all ifaces.
360 : * @return 0 if all net_if_up and conn_mgr_if_connect calls returned 0, otherwise the first nonzero
361 : * value returned by either net_if_up or conn_mgr_if_connect.
362 : */
363 1 : int conn_mgr_all_if_connect(bool skip_ignored);
364 :
365 : /**
366 : * @brief Convenience function that disconnects all available ifaces that support connectivity
367 : * without putting them into admin-down state (unless auto-down is enabled for the iface).
368 : *
369 : * Essentially a wrapper for @ref net_if_down.
370 : *
371 : * @param skip_ignored - If true, only affect ifaces that aren't ignored by conn_mgr.
372 : * Otherwise, affect all ifaces.
373 : * @return 0 if all net_if_up and conn_mgr_if_connect calls returned 0, otherwise the first nonzero
374 : * value returned by either net_if_up or conn_mgr_if_connect.
375 : */
376 1 : int conn_mgr_all_if_disconnect(bool skip_ignored);
377 :
378 : /**
379 : * @}
380 : */
381 :
382 : #ifdef __cplusplus
383 : }
384 : #endif
385 :
386 : #endif /* ZEPHYR_INCLUDE_CONN_MGR_CONNECTIVITY_H_ */
|
