How to use the Windows NLM API to get notified of new network connectivity

• Download source code - 19.8 KB

Introduction

An application often needs to know if the machine has internet connectivity and take actions depending on that. In this sample, we are looking at the usage of the Windows NLM API in managed code so that an application can choose to respond to internet connectivity changes. There are many other specific NLM APIs for checking domain connectivity, network adapter interfaces etc., that haven't been mentioned in this article; you can refer to this link for further details. The downloadable zip file has the source code.

Using the code

For a managed code project, you need to reference the netprofm.dll in the \windows\system32\ directory. Here, m_nlm is a NetworkListManager COM object created to provide NLM functionalities. In the Main function, we can get an enumerator of all the networks and try to list their names one by one. You can use the API to list the properties of each network. Your machine might be connected to a free library hotspot, and it might also be connected to a corporate network via VPN or DirectAccess. In this case, there will be two networks listed, one with public internet access and the other with domain network access.

AppNetworkListUser()
{
    m_nlm = new NetworkListManager();
}
static void Main(string[] args)
{
    AppNetworkListUser nlmUser = new AppNetworkListUser();
    Console.WriteLine("Is the machine connected to internet? " + 
                      nlmUser.NLM.IsConnectedToInternet.ToString());
    //List the connected networks. There are many other APIs 
    //can be called to get network information.
    IEnumNetworks Networks = 
      nlmUser.NLM.GetNetworks(NLM_ENUM_NETWORK.NLM_ENUM_NETWORK_CONNECTED);
    foreach (INetwork item in Networks)
    {
        Console.WriteLine("Connected Network:" + item.GetName() );
    }
    nlmUser.AdviseforNetworklistManager();
    Console.WriteLine("Press any key and enter to finish the program");
    String temp; 
    temp = Console.ReadLine();
    nlmUser.UnAdviseforNetworklistManager();
}

In the Main function, we also used AdviseforNetworklistManager to subscribe to any network connectivity changes for the machine, so that your ConnectivityChanged(NLM_CONNECTIVITY) method will be invoked if there is any network connectivity change. This is the method that you could use to take some actions if your machine gets connected to the internet. Before your application leaves the scene, you need to unsubscribe the event notifications about network connectivity changes. The event subscription method will find the connection point to get the INetworkListManager event as in the code below:

public void AdviseforNetworklistManager()
{
    Console.WriteLine("Subscribing the INetworkListManagerEvents");
    IConnectionPointContainer icpc = (IConnectionPointContainer)m_nlm;
    //similar event subscription can be used 
    //for INetworkEvents and INetworkConnectionEvents
    Guid tempGuid = typeof(INetworkListManagerEvents).GUID;
    icpc.FindConnectionPoint(ref tempGuid , out m_icp);
    m_icp.Advise(this, out m_cookie);
}

In ConnectivityChanged(NLM_CONNECTIVITY), we provide a sample to output the current machine's internet connectivity to the Console. Your app can take custom actions such as start downloading new data when connected to the internet etc.

public void ConnectivityChanged(NLM_CONNECTIVITY newConnectivity)
{
    Console.WriteLine("");
    Console.WriteLine("-------------------------------------------" + 
                      "--------------------------------");
    Console.WriteLine("NetworkList just informed the connectivity change." + 
                      " The new connectivity is:");
    if (newConnectivity == NLM_CONNECTIVITY.NLM_CONNECTIVITY_DISCONNECTED)
    {
        Console.WriteLine("The machine is disconnected from Network");
    }
    if (((int)newConnectivity & 
         (int)NLM_CONNECTIVITY.NLM_CONNECTIVITY_IPV4_INTERNET) != 0)
    {
        Console.WriteLine("The machine is connected to internet " + 
                          "with IPv4 capability ");
    }
    if (((int)newConnectivity & 
         (int)NLM_CONNECTIVITY.NLM_CONNECTIVITY_IPV6_INTERNET) != 0)
    {
        Console.WriteLine("The machine is connected to internet " + 
                          "with IPv6 capability ");
    }
    if ((((int)newConnectivity & 
          (int)NLM_CONNECTIVITY.NLM_CONNECTIVITY_IPV4_INTERNET) == 0) && 
          (((int)newConnectivity & 
          (int)NLM_CONNECTIVITY.NLM_CONNECTIVITY_IPV6_INTERNET) == 0))
    {
        Console.WriteLine("The machine is not connected to internet yet ");
    }
}

Output

Here is the output after we unplug the Ethernet cable from the computer and plug it back again. You can see the app get notified of the internet connectivity changes:

History

• 0.1 - Added a brief description of the NLM API sample.