Share via

Networking_GetInterfaceConnectionStatus Function

  • Article

Header: #include <applibs/networking.h>

Gets the network connection status for a network interface. When Networking_GetInterfaceConnectionStatus is called, the OS returns the last known status and attempts to update the specified interface status in the Networking_InterfaceConnectionStatus enum.

The Networking_InterfaceConnectionStatus enum returned reflects the last known status of the interface, network connectivity, IP address, and internet connection. When Networking_GetInterfaceConnectionStatus is called, the OS attempts to update these status flags and make a call to http://www.msftconnecttest.com as noted in Azure Sphere OS networking requirements, in order to determine if the device has internet connectivity.

An application may take action based on the Networking_InterfaceConnectionStatus_ConnectedToInternet status, which indicates if the device is connected to the internet. However, for various reasons, network or internet connectivity might be lost between the time the status was updated and the time the application attempts to connect to the internet. Therefore, the application should include logic that allows for smart choices when encountering changes in network and internet availability. The application should handle connection errors and adapt accordingly.

If the status returned indicates that the device is not connected to the internet, the application may call Networking_GetInterfaceConnectionStatus again in order to determine when the device status is changed.

If Networking_InterfaceConnectionStatus_ConnectedToInternet indicates that the device is connected to the internet, the device should not poll for status more than once every 90 seconds. If this connection status function repeatedly returns the indication that the device is connected to the internet, the OS throttles the status check if the polling interval is too short. The recommended application polling interval is one request/two minutes.

int Networking_GetInterfaceConnectionStatus(const char *networkInterfaceName, Networking_InterfaceConnectionStatus *outStatus);

Parameters

Errors

Returns -1 if an error is encountered and sets errno to the error value.

  • EFAULT: the outStatus parameter is NULL.

  • ENOENT: the networkInterfaceName interface does not exist.

  • EAGAIN: the networking stack isn't ready.

Any other errno may also be specified; such errors aren't deterministic and the same behavior might not be retained through system updates.

Return value

Returns 0 for success, -1 for failure, in which case errno is set to the error value.

Concepts and samples