Class WifiNetworkHelper

Namespace

nanoFramework.Networking

Assembly

System.Device.Wifi.dll

Network helper class providing helper methods to assist on connecting to a Wifi network.

public static class WifiNetworkHelper

Inheritance

object

WifiNetworkHelper

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Properties

HelperException

Exception that occurred when waiting for the network to become ready.

public static Exception HelperException { get; }

Property Value

Exception

NetworkReady

Event signaling that networking it's ready.

public static ManualResetEvent NetworkReady { get; }

Property Value

ManualResetEvent

Remarks

The conditions for this are setup in the call to SetupNetworkHelper(bool). It will be a composition of network connected, IpAddress available and valid system DateTime.

When using SetupNetworkHelper(bool), this event is reset when the connection is lost and re-signaled when it is restored, accurately reflecting live network state.

Status

Status of NetworkHelper.

public static NetworkHelperStatus Status { get; }

Property Value

NetworkHelperStatus

WifiAdapter

Gets the Wifi Adapter.

public static WifiAdapter WifiAdapter { get; }

Property Value

WifiAdapter

Methods

ConnectDhcp(string, string, WifiReconnectionKind, bool, int, CancellationToken)

This method will connect the network with DHCP enabled, for your SSID and try to connect to it with the credentials you've passed. This will save as well the configuration of your network. This method is retryable and can be called multiple times after a previous call times out or fails.

public static bool ConnectDhcp(string ssid, string password, WifiReconnectionKind reconnectionKind = WifiReconnectionKind.Automatic, bool requiresDateTime = false, int wifiAdapterId = 0, CancellationToken token = default)

Parameters

ssid string

The SSID of the network you are trying to connect to.

password string

The password associated to the SSID of the network you are trying to connect to.

reconnectionKind WifiReconnectionKind

The WifiReconnectionKind to setup for the connection.

requiresDateTime bool

Set to true if valid date and time are required.

wifiAdapterId int

The index of the Wifi adapter to be used. Relevant only if there are multiple Wifi adapters.

token CancellationToken

A CancellationToken used for timing out the operation.

Returns

bool

true on success. On failure returns false and details with the cause of the failure are made available in the Status property

ConnectFixAddress(string, string, IPConfiguration, WifiReconnectionKind, bool, int, CancellationToken)

This method will connect the network with the static IP address you are providing, for your SSID and try to connect to it with the credentials you've passed. This will save as well the configuration of your network. This method is retryable and can be called multiple times after a previous call times out or fails.

public static bool ConnectFixAddress(string ssid, string password, IPConfiguration ipConfiguration, WifiReconnectionKind reconnectionKind = WifiReconnectionKind.Automatic, bool requiresDateTime = false, int WifiAdapter = 0, CancellationToken token = default)

Parameters

ssid string

The SSID you are trying to connect to.

password string

The password associated to the SSID you are trying to connect to.

ipConfiguration IPConfiguration

The static IPv4 configuration to apply to the Wifi network interface.

reconnectionKind WifiReconnectionKind

The WifiReconnectionKind to setup for the connection.

requiresDateTime bool

Set to true if valid date and time are required.

WifiAdapter int

The index of the Wifi adapter to be used. Relevant only if there are multiple Wifi adapters.

token CancellationToken

A CancellationToken used for timing out the operation.

Returns

bool

true on success. On failure returns false and details with the cause of the failure are made available in the Status property

Disconnect()

Disconnect from the network.

public static void Disconnect()

Reconnect(bool, int, CancellationToken)

Waits for the platform's automatic WiFi reconnection to produce a valid IP address. This method does not actively send join credentials to the access point. It relies on the Automatic behaviour previously configured when calling ConnectDhcp(string, string, WifiReconnectionKind, bool, int, CancellationToken) or ConnectFixAddress(string, string, IPConfiguration, WifiReconnectionKind, bool, int, CancellationToken).

public static bool Reconnect(bool requiresDateTime = false, int wifiAdapterId = 0, CancellationToken token = default)

Parameters

requiresDateTime bool

Set to true if valid date and time are required.

wifiAdapterId int

The index of the Wifi adapter to be used. Relevant only if there are multiple Wifi adapters.

token CancellationToken

A CancellationToken used for timing out the operation.

Returns

bool

true on success. On failure returns false and details with the cause of the failure are made available in the Status property

Remarks

Use this method only when the device credentials are already stored and the platform is expected to reconnect automatically. If you need an explicit reconnect with credentials, call ConnectDhcp(string, string, WifiReconnectionKind, bool, int, CancellationToken) or ConnectFixAddress(string, string, IPConfiguration, WifiReconnectionKind, bool, int, CancellationToken) instead. This method is retryable and can be called multiple times.

Reset()

Resets the WifiNetworkHelper to its initial state, allowing SetupNetworkHelper(bool) to be called again or the network configuration to be changed.

public static void Reset()

Remarks

Call this before switching to a different WiFi network or restarting the event-based helper. This method does not disconnect the WiFi adapter; call Disconnect() first if needed.

ScanAndConnectDhcp(string, string, WifiReconnectionKind, bool, int, CancellationToken)

This method will scan and connect the network with DHCP enabled, for your SSID and try to connect to it with the credentials you've passed. This will save as well the configuration of your network. This method is retryable and can be called multiple times after a previous call times out or fails.

public static bool ScanAndConnectDhcp(string ssid, string password, WifiReconnectionKind reconnectionKind = WifiReconnectionKind.Automatic, bool requiresDateTime = false, int WifiAdapter = 0, CancellationToken token = default)

Parameters

ssid string

The SSID you are trying to connect to.

password string

The password associated to the SSID you are trying to connect to.

reconnectionKind WifiReconnectionKind

The reconnection type to the network.

requiresDateTime bool

Set to true if valid date and time are required.

WifiAdapter int

The index of the Wifi adapter to be used. Relevant only if there are multiple Wifi adapters.

token CancellationToken

A CancellationToken used for timing out the operation.

Returns

bool

true on success. On failure returns false and details with the cause of the failure are made available in the Status property

SetupNetworkHelper(bool)

This method will setup the network configurations so that the NetworkReady event will fire when the required conditions are met. That will be the network connection to be up, having a valid IpAddress and optionally for a valid date and time to become available.

public static void SetupNetworkHelper(bool requiresDateTime = false)

Parameters

requiresDateTime bool

Set to true if valid date and time are required.

Exceptions

InvalidOperationException

If called more than once without an intervening call to Reset().

NotSupportedException

There is no network interface configured. Open the 'Edit Network Configuration' in Device Explorer and configure one.

SetupNetworkHelper(string, string, WifiReconnectionKind, bool)

This method will setup the network configurations so that the NetworkReady event will fire when the required conditions are met. That will be the network connection to be up, having a valid IpAddress and optionally for a valid date and time to become available.

public static void SetupNetworkHelper(string ssid, string password, WifiReconnectionKind reconnectionKind = WifiReconnectionKind.Automatic, bool requiresDateTime = false)

Parameters

ssid string

The SSID of the network you are trying to connect to.

password string

The password associated to the SSID of the network you are trying to connect to.

reconnectionKind WifiReconnectionKind

The WifiReconnectionKind to setup for the connection.

requiresDateTime bool

Set to true if valid date and time are required.

Exceptions

InvalidOperationException

If called more than once without an intervening call to Reset().

NotSupportedException

There is no network interface configured. Open the 'Edit Network Configuration' in Device Explorer and configure one.

SetupNetworkHelper(IPConfiguration, bool)

This method will setup the network configurations so that the NetworkReady event will fire when the required conditions are met. That will be the network connection to be up, having a valid IpAddress and optionally for a valid date and time to become available.

public static void SetupNetworkHelper(IPConfiguration ipConfiguration, bool requiresDateTime = false)

Parameters

ipConfiguration IPConfiguration

The static IP configuration you want to apply.

requiresDateTime bool

Set to true if valid date and time are required.

Exceptions

InvalidOperationException

If called more than once without an intervening call to Reset().

NotSupportedException

There is no network interface configured. Open the 'Edit Network Configuration' in Device Explorer and configure one.