Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

Connection Manager API. More...

Functions

void conn_mgr_mon_resend_status (void)
 Resend L4 connectivity and DNS readiness events depending on current status.
bool conn_mgr_dns_is_ready (void)
 Check whether name resolution is currently available.
uint32_t conn_mgr_get_readiness (void)
 Get the current readiness flags.
net_sa_family_t conn_mgr_get_ready_addr_family (void)
 Get the address family to use in getaddrinfo() hints.
int conn_mgr_wait_ready (uint32_t mask, uint32_t *last_seen, k_timeout_t timeout)
 Wait until it is time to try to connect.
void conn_mgr_ignore_iface (struct net_if *iface)
 Mark an iface to be ignored by conn_mgr.
void conn_mgr_watch_iface (struct net_if *iface)
 Watch (stop ignoring) an iface.
bool conn_mgr_is_iface_ignored (struct net_if *iface)
 Check whether the provided iface is currently ignored.
void conn_mgr_ignore_l2 (const struct net_l2 *l2)
 Mark an L2 to be ignored by conn_mgr.
void conn_mgr_watch_l2 (const struct net_l2 *l2)
 Watch (stop ignoring) an L2.

Readiness flags

#define CONN_MGR_READY_IPV4   BIT(0)
 An iface is ready with IPv4, see NET_EVENT_L4_IPV4_CONNECTED.
#define CONN_MGR_READY_IPV6   BIT(1)
 An iface is ready with IPv6, see NET_EVENT_L4_IPV6_CONNECTED.
#define CONN_MGR_READY_IP_ANY   BIT(2)
 CONN_MGR_READY_IPV4 or CONN_MGR_READY_IPV6 is set.
#define CONN_MGR_READY_DNS   BIT(3)
 A unicast DNS server is configured for a ready IP family, or name resolution is offloaded, see conn_mgr_dns_is_ready.

Detailed Description

Connection Manager API.

Since
2.0
Version
0.1.0

Macro Definition Documentation

◆ CONN_MGR_READY_DNS

#define CONN_MGR_READY_DNS   BIT(3)

#include <zephyr/net/conn_mgr_monitor.h>

A unicast DNS server is configured for a ready IP family, or name resolution is offloaded, see conn_mgr_dns_is_ready.

mDNS and LLMNR do not use a unicast DNS server. Names resolved with them can work while this flag is cleared, so do not wait for it when only such names are used.

◆ CONN_MGR_READY_IP_ANY

#define CONN_MGR_READY_IP_ANY   BIT(2)

◆ CONN_MGR_READY_IPV4

#define CONN_MGR_READY_IPV4   BIT(0)

#include <zephyr/net/conn_mgr_monitor.h>

An iface is ready with IPv4, see NET_EVENT_L4_IPV4_CONNECTED.

◆ CONN_MGR_READY_IPV6

#define CONN_MGR_READY_IPV6   BIT(1)

#include <zephyr/net/conn_mgr_monitor.h>

An iface is ready with IPv6, see NET_EVENT_L4_IPV6_CONNECTED.

Function Documentation

◆ conn_mgr_dns_is_ready()

bool conn_mgr_dns_is_ready ( void )

#include <zephyr/net/conn_mgr_monitor.h>

Check whether name resolution is currently available.

A unicast DNS server being configured does not mean that it can be reached. Requires CONFIG_DNS_RESOLVER or offloaded name resolution.

Return values
trueA unicast DNS server is configured for a ready iface and address family, or name resolution is offloaded and an iface is ready.
falseName resolution is not available.

◆ conn_mgr_get_readiness()

uint32_t conn_mgr_get_readiness ( void )

#include <zephyr/net/conn_mgr_monitor.h>

Get the current readiness flags.

Without CONFIG_NET_CONNECTION_MANAGER, readiness is not tracked and all flags are set.

The function takes an internal lock and can block for a short time on it.

Returns
Bitmask of readiness flags currently set.

◆ conn_mgr_get_ready_addr_family()

net_sa_family_t conn_mgr_get_ready_addr_family ( void )

#include <zephyr/net/conn_mgr_monitor.h>

Get the address family to use in getaddrinfo() hints.

Set the ai_family field of the getaddrinfo() hints to the returned value. getaddrinfo() then returns only addresses of the IP family that is ready. If both IP families are ready, or none is ready, getaddrinfo() returns addresses of all families. Without CONFIG_NET_CONNECTION_MANAGER, this returns NET_AF_UNSPEC.

The function takes an internal lock and can block for a short time on it.

Return values
NET_AF_INETOnly IPv4 is ready.
NET_AF_INET6Only IPv6 is ready.
NET_AF_UNSPECBoth or neither IP family is ready.

◆ conn_mgr_ignore_iface()

void conn_mgr_ignore_iface ( struct net_if * iface)

#include <zephyr/net/conn_mgr_monitor.h>

Mark an iface to be ignored by conn_mgr.

Ignoring an iface forces conn_mgr to consider it unready/disconnected.

This means that events related to the iface connecting/disconnecting will not be fired, and if the iface was connected before being ignored, events will be fired as though it disconnected at that moment.

Parameters
ifaceiface to be ignored.

◆ conn_mgr_ignore_l2()

void conn_mgr_ignore_l2 ( const struct net_l2 * l2)

#include <zephyr/net/conn_mgr_monitor.h>

Mark an L2 to be ignored by conn_mgr.

This is a wrapper for conn_mgr_ignore_iface that ignores all ifaces that use the L2.

Parameters
l2L2 to be ignored.

◆ conn_mgr_is_iface_ignored()

bool conn_mgr_is_iface_ignored ( struct net_if * iface)

#include <zephyr/net/conn_mgr_monitor.h>

Check whether the provided iface is currently ignored.

Parameters
ifaceThe iface to check.
Return values
trueif the iface is being ignored by conn_mgr.
falseif the iface is being watched by conn_mgr.

◆ conn_mgr_mon_resend_status()

void conn_mgr_mon_resend_status ( void )

#include <zephyr/net/conn_mgr_monitor.h>

Resend L4 connectivity and DNS readiness events depending on current status.

Events covered:

  • NET_EVENT_L4_CONNECTED / NET_EVENT_L4_DISCONNECTED
  • NET_EVENT_L4_IPV4_CONNECTED / NET_EVENT_L4_IPV4_DISCONNECTED
  • NET_EVENT_L4_IPV6_CONNECTED / NET_EVENT_L4_IPV6_DISCONNECTED
  • NET_EVENT_L4_DNS_READY / NET_EVENT_L4_DNS_LOST

◆ conn_mgr_wait_ready()

int conn_mgr_wait_ready ( uint32_t mask,
uint32_t * last_seen,
k_timeout_t timeout )

#include <zephyr/net/conn_mgr_monitor.h>

Wait until it is time to try to connect.

Returns 0, meaning "try to connect now", when all flags in mask are ready and one of the following is true:

  • any flag in mask was gained after last_seen,
  • timeout expired.

A flag is gained when an iface becomes ready for an IP family, or when name resolution becomes available.

Set last_seen to 0 before the first call and do not change it afterwards. A retry loop then waits for timeout or a gain between attempts. A NULL last_seen acts like 0 and is not written back. Use it only for a one-time wait.

Without CONFIG_NET_CONNECTION_MANAGER, the network is considered ready.

In a net_mgmt event callback or on the work queue delivering net_mgmt events, timeout must be K_NO_WAIT.

Note
timeout limits only the wait for readiness. The function always takes an internal lock and can block for a short time on it, also with K_NO_WAIT. For this reason it cannot be called from an ISR, even with K_NO_WAIT.
In a loop that retries on -EAGAIN, do not use K_NO_WAIT or a zero timeout. Otherwise, the loop busy-spins while the network is not ready.
Parameters
maskBitwise OR of readiness flags to wait for.
last_seenLast readiness change seen by the caller, or NULL. Updated on return, unless -EINVAL or -EDEADLK is returned.
timeoutMaximum time to wait.
Return values
0All flags in mask are ready. Try to connect now.
-EAGAINA flag in mask was not ready when timeout expired.
-EINVALmask is 0 or contains an unknown flag.
-EDEADLKCalled with a non-zero timeout from net_mgmt event context.

◆ conn_mgr_watch_iface()

void conn_mgr_watch_iface ( struct net_if * iface)

#include <zephyr/net/conn_mgr_monitor.h>

Watch (stop ignoring) an iface.

conn_mgr will no longer be forced to consider the iface unreadly/disconnected.

Events related to the iface connecting/disconnecting will no longer be blocked, and if the iface was connected before being watched, events will be fired as though it connected in that moment.

All ifaces default to watched at boot.

Parameters
ifaceiface to no longer ignore.

◆ conn_mgr_watch_l2()

void conn_mgr_watch_l2 ( const struct net_l2 * l2)

#include <zephyr/net/conn_mgr_monitor.h>

Watch (stop ignoring) an L2.

This is a wrapper for conn_mgr_watch_iface that watches all ifaces that use the L2.

Parameters
l2L2 to watch.