IP Adapter Information

This section provides information on how to retrieve and manage IP adapter configuration details using the IP Helper API.

Overview

The IP Helper API offers functions to query and configure network interface parameters on Windows operating systems. This includes obtaining information about network adapters, their IP addresses, MAC addresses, status, and other relevant configuration data.

Key Structures and Functions

IP_ADAPTER_INFO Structure: A structure that contains information about a network adapter.
GetAdaptersInfo Function: Retrieves detailed information about network adapters installed on the local computer.
GetAdapterAddresses Function: Retrieves the addresses associated with network adapters.

IP_ADAPTER_INFO Structure

The IP_ADAPTER_INFO structure contains information about a network adapter. This structure is used by the GetAdaptersInfo function.

                    
typedef struct _IP_ADAPTER_INFO {
    struct _IP_ADAPTER_INFO* Next;              // Pointer to the next adapter info structure
    char                     AdapterName[NDIS_MAX_ADAPTER_NAME_LENGTH + 4]; // Adapter name
    char                     Description[IPCONFIG_MAX_PRI_LABEL_LENGTH + 4]; // Adapter description
    ULONG                    AddressLength;      // Length of the adapter's hardware address
    BYTE                     bAddress[MAX_ADAPTER_ADDRESS_LENGTH]; // Hardware address
    ULONG                    Index;              // Index of the adapter
    ULONG                    Type;               // Type of adapter
    ULONG                    DhcpEnabled;        // Whether DHCP is enabled for this adapter
    IP_ADDR_STRING           CurrentIpAddress;   // Current IP address
    IP_ADDR_STRING           IpMask;             // IP address mask
    IP_ADDR_STRING           GatewayAddress;     // Default gateway address
    IP_ADDR_STRING           Dhcpv4Server;       // DHCP server address
    IP_ADDR_STRING           Dhcpv4LeaseExpires; // DHCP lease expiration time
    IP_ADDR_STRING           Dhcpv4NextServer;   // Next server in DHCP bootp sequence
    IP_ADDR_STRING           Dhcpv6Server;       // DHCPv6 server address
    IP_ADDR_STRING           Dhcpv6LeaseExpires; // DHCPv6 lease expiration time
    IP_ADDR_STRING           Dhcpv6NextServer;   // Next server in DHCPv6 bootp sequence
    IP_ADDR_STRING           RamMask;            // Mask for RAM addresses
    IP_ADDR_STRING           BridgedToAdapter;   // Name of adapter this is bridged to
} IP_ADAPTER_INFO, *PIP_ADAPTER_INFO;
                    
                

Structure Members

Member	Description
`Next`	Pointer to the next `IP_ADAPTER_INFO` structure in the linked list.
`AdapterName`	The name of the adapter (e.g., "Ethernet 0").
`Description`	A description of the adapter (e.g., "Realtek PCIe GbE Family Controller").
`AddressLength`	The length, in bytes, of the adapter's hardware address.
`bAddress`	The adapter's hardware address (MAC address).
`Index`	The index of the adapter. This is a unique value identifying the adapter.
`Type`	The type of adapter. For a list of possible values, see Adapter Type Constants.
`DhcpEnabled`	A flag indicating if DHCP is enabled for this adapter (1 if enabled, 0 if disabled).
`CurrentIpAddress`	The current IP address assigned to the adapter.
`IpMask`	The IP subnet mask for the adapter.
`GatewayAddress`	The default gateway address for the adapter.
`Dhcpv4Server`	The IP address of the DHCPv4 server.
`Dhcpv4LeaseExpires`	The time when the DHCPv4 lease expires.
`Dhcpv4NextServer`	The IP address of the next server in the DHCP bootp sequence.
`Dhcpv6Server`	The IP address of the DHCPv6 server.
`Dhcpv6LeaseExpires`	The time when the DHCPv6 lease expires.
`Dhcpv6NextServer`	The IP address of the next server in the DHCPv6 bootp sequence.
`RamMask`	The mask for RAM addresses.
`BridgedToAdapter`	The name of the adapter to which this adapter is bridged.

GetAdaptersInfo Function

The GetAdaptersInfo function retrieves detailed information about network adapters installed on the local computer. It returns a linked list of IP_ADAPTER_INFO structures, one for each adapter.

                    
ULONG WINAPI GetAdaptersInfo(
  _Out_writes_bytes_to_opt_(*SizePointer, *SizePointer) PIP_ADAPTER_INFO AdapterInfo,
  _Inout_ PULONG SizePointer
);

Parameters

Parameter Description

Parameter	Description
`AdapterInfo`	A pointer to a buffer that receives a linked list of `IP_ADAPTER_INFO` structures. If this buffer is not large enough to contain the adapter information, the function returns `ERROR_BUFFER_OVERFLOW` and the value pointed to by `SizePointer` is updated to the required buffer size.
`SizePointer`	On input, this parameter specifies the size, in bytes, of the buffer pointed to by the `AdapterInfo` parameter. On output, if the buffer is not large enough, this parameter receives the required buffer size in bytes.

AdapterInfo

A pointer to a buffer that receives a linked list of IP_ADAPTER_INFO structures. If this buffer is not large enough to contain the adapter information, the function returns ERROR_BUFFER_OVERFLOW and the value pointed to by SizePointer is updated to the required buffer size.

SizePointer

On input, this parameter specifies the size, in bytes, of the buffer pointed to by the AdapterInfo parameter.

On output, if the buffer is not large enough, this parameter receives the required buffer size in bytes.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the buffer pointed to by AdapterInfo is not large enough to hold the adapter information, the return value is ERROR_BUFFER_OVERFLOW, and the value pointed to by SizePointer is updated with the required buffer size.

If the function fails, the return value can be one of the error codes defined in WinError.h.

GetAdapterAddresses Function

The GetAdapterAddresses function retrieves the adapter addresses associated with the local computer. This function is more versatile than GetAdaptersInfo as it supports both IPv4 and IPv6 addresses and provides more detailed information.

                    
ULONG WINAPI GetAdapterAddresses(
  _In_ ULONG               Family,
  _In_ DWORD               Flags,
  _In_ PVOID               Reserved,
  _Inout_updates_bytes_to_opt_(*SizePointer, *SizePointer) PIP_ADAPTER_ADDRESSES AdapterAddresses,
  _Inout_ PULONG            SizePointer
);
                    
                

Remarks

The GetAdapterAddresses function returns information about network adapters, including their IP addresses (both IPv4 and IPv6), MAC addresses, and other configuration details. It returns a linked list of IP_ADAPTER_ADDRESSES structures.

This function is the recommended way to retrieve network adapter information, especially for applications that need to support both IPv4 and IPv6.

The Family parameter specifies the address family (e.g., AF_UNSPEC for all families, AF_INET for IPv4, AF_INET6 for IPv6).

The Flags parameter can be used to specify additional options, such as filtering by adapter type.