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