Windows Networking API

Documentation for Windows Network Connectivity

Understanding Network Connections in Windows

This section delves into the APIs and concepts related to managing and querying network connections within the Windows operating system. Effective network management is crucial for application development, system administration, and ensuring robust connectivity.

Windows provides a rich set of interfaces and functions to interact with network adapters, IP addresses, routing tables, and connection states. Developers can leverage these tools to build applications that are network-aware, perform network diagnostics, or manage network configurations programmatically.

Important: Accessing and modifying network configurations can have significant system-wide implications. Always ensure you have the necessary permissions and understand the potential consequences before making changes.

Key Concepts

Core Connection APIs

The following APIs are fundamental for working with network connections in Windows.

Network Information APIs

Retrieve information about the current network configuration and status.

GetAdaptersInfo / GetAdaptersAddresses

ULONG WINAPI GetAdaptersInfo(IP_ADAPTER_INFO *AdapterInfo, PULONG SizePointer);

Retrieves information about the network adapters installed on the local computer. Deprecated in favor of GetAdaptersAddresses.

DWORD WINAPI GetAdaptersAddresses(ULONG Family, ULONG Flags, PVOID Reserved, PIP_ADAPTER_ADDRESSES AdapterAddresses, PULONG SizePointer);

Retrieves adapter configuration information for the local computer. This function is more modern and supports IPv6.

Parameters
  • Family: The address family (e.g., AF_INET for IPv4, AF_INET6 for IPv6).
  • Flags: Options to control the information returned.
  • AdapterAddresses: A pointer to a buffer that receives the adapter configuration data.
  • SizePointer: On input, specifies the size of the buffer pointed to by AdapterAddresses. On output, it receives the actual size of the buffer required.
Returns ERROR_SUCCESS on success, or an appropriate error code otherwise.
Example Usage (Conceptual C++)
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>

#pragma comment(lib, "IPHLPAPI.lib")
#pragma comment(lib, "WS2_32.lib")

int main() {
    ULONG family = AF_INET;
    ULONG flags = 0;
    ULONG size = 0;
    PIP_ADAPTER_ADDRESSES pAdapterAddresses = NULL;

    // Get the required buffer size
    if (GetAdaptersAddresses(family, flags, NULL, NULL, &size) == ERROR_BUFFER_OVERFLOW) {
        pAdapterAddresses = (PIP_ADAPTER_ADDRESSES)malloc(size);
        if (pAdapterAddresses == NULL) {
            fprintf(stderr, "Memory allocation failed.\n");
            return 1;
        }
    }

    // Get adapter addresses
    DWORD dwRetVal = GetAdaptersAddresses(family, flags, NULL, pAdapterAddresses, &size);

    if (dwRetVal == ERROR_SUCCESS) {
        printf("Successfully retrieved adapter addresses.\n");
        PIP_ADAPTER_ADDRESSES pCurrentAdapter = pAdapterAddresses;
        while (pCurrentAdapter) {
            wprintf(L"Adapter Name: %s\n", pCurrentAdapter->FriendlyName);
            if (pCurrentAdapter->FirstUnicastAddress) {
                PIP_UNICAST_ADDRESS pUnicast = pCurrentAdapter->FirstUnicastAddress;
                while (pUnicast) {
                    if (pUnicast->Address.lpSockaddr->sa_family == AF_INET) {
                        CHAR ipstr[INET_ADDRSTRLEN);
                        struct sockaddr_in *ipv4 = (struct sockaddr_in *)pUnicast->Address.lpSockaddr;
                        inet_ntop(AF_INET, &(ipv4->sin_addr), ipstr, sizeof ipstr);
                        wprintf(L"  IPv4 Address: %s\n", ipstr);
                    } else if (pUnicast->Address.lpSockaddr->sa_family == AF_INET6) {
                         // Handle IPv6 if needed
                    }
                    pUnicast = pUnicast->Next;
                }
            }
            pCurrentAdapter = pCurrentAdapter->Next;
        }
    } else {
        fprintf(stderr, "Error retrieving adapter addresses: %d\n", dwRetVal);
    }

    if (pAdapterAddresses) {
        free(pAdapterAddresses);
    }
    return 0;
}

Network Connection Status

GetNetworkConnectivityHint

HRESULT WINAPI GetNetworkConnectivityHint(NLM_NETWORK_PROGRESS_CALLBACK pCallback, PVOID pvClientContext, PHANDLE phNetworkConnection);

Provides a callback-based mechanism to receive network connectivity status updates.

Parameters
  • pCallback: A pointer to a callback function that will be invoked with connectivity status changes.
  • pvClientContext: User-defined context passed to the callback.
  • phNetworkConnection: A handle to the network connection object.
Returns an HRESULT indicating success or failure.
This API is designed for real-time notifications and is more complex than simply querying the current state. It's useful for applications that need to react dynamically to network changes.

IP Helper Functions

A set of functions for network configuration and management.

IP Helper API

This API includes functions such as:

  • GetIpAddrTable: Retrieves the IP address table.
  • GetRouteTable: Retrieves routing information.
  • CreateIpForwardEntry / DeleteIpForwardEntry: For manipulating routes.

Refer to the dedicated IP Helper API documentation for detailed information.

Common Scenarios