GetAdaptersInfo Function

Available on: Windows 10+ Windows 7+ Windows 8+

Syntax

DWORD GetAdaptersInfo(
  PIP_ADAPTER_INFO pAdapterInfo,
  ULONG            *pOutBufLen
);

Parameters

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

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

If the function fails, the return value is one of the following error codes:

Return code Description
ERROR_INVALID_PARAMETER One of the parameters is invalid.
ERROR_NOT_SUPPORTED The operation is not supported on the local machine.
ERROR_GEN_FAILURE A general error occurred.

Remarks

The GetAdaptersInfo function retrieves information about the network adapters on the local computer.

This function is intended for use on the local computer. To retrieve information about network adapters on a remote computer, use the GetAdaptersInfoEx function.

If the buffer pointed to by pAdapterInfo is not large enough to hold the adapter information, GetAdaptersInfo returns ERROR_BUFFER_OVERFLOW and sets the value of pOutBufLen to the required buffer size.

The IP_ADAPTER_INFO structure contains information about an adapter, including its IP address, MAC address, and gateway address. The structures returned by GetAdaptersInfo are linked together using the Next member.

The Index member of the IP_ADAPTER_INFO structure is an arbitrary adapter index. An application should not rely on the Index member of this structure.

The DhcpEnabled member is only valid if the adapter is configured to obtain an IP address from a DHCP server. If DhcpEnabled is TRUE, then the DhcpServer and LeaseObtained and LeaseExpires members are valid. Otherwise, these members are not valid.

The GatewayList, DhcpServer, and BroadcastAddr members are arrays that can hold multiple entries. The NumEntries member indicates the number of entries in these arrays.

To iterate through the list of adapters, use a loop:

// Example pseudo-code
ULONG ulOutBufLen = sizeof(IP_ADAPTER_INFO);
IP_ADAPTER_INFO* pAdapterInfo = NULL;

if (GetAdaptersInfo(pAdapterInfo, &ulOutBufLen) == ERROR_BUFFER_OVERFLOW) {
    pAdapterInfo = (IP_ADAPTER_INFO*)malloc(ulOutBufLen);
    if (pAdapterInfo == NULL) {
        // Handle memory allocation error
        return;
    }
}

if (GetAdaptersInfo(pAdapterInfo, &ulOutBufLen) == ERROR_SUCCESS) {
    IP_ADAPTER_INFO* pCurrentAdapter = pAdapterInfo;
    while (pCurrentAdapter) {
        // Process adapter information (e.g., pCurrentAdapter->IpAddressList.IpAddress.String)
        // ...
        pCurrentAdapter = pCurrentAdapter->Next;
    }
}

if (pAdapterInfo) {
    free(pAdapterInfo);
}

IP_ADAPTER_INFO Structure

The IP_ADAPTER_INFO structure contains information about an adapter. It is part of the IP Helper API.

typedef struct _IP_ADAPTER_INFO {
  struct _IP_ADAPTER_INFO  *Next;
  DWORD                    CommittedMTU;
  DWORD                    AdapterName;
  DWORD                    Description;
  DWORD                    AddressLength;
  BYTE                     PhysicalAddress[MAX_ADAPTER_ADDRESS_LENGTH];
  DWORD                    DnsSuffix;
  DWORD                    IsAutomaticIPEnabled;
  DWORD                    HaveWins;
  DWORD                    PrimaryWinsServer;
  DWORD                    SecondaryWinsServer;
  DWORD                    LeaseObtained;
  DWORD                    LeaseExpires;
  DWORD                    DhcpEnabled;
  DWORD                    DhcpServer;
  DWORD                    GatewayList;
  DWORD                    GatewayCount;
  DWORD                    GatewayExists;
  DWORD                    IpAddressList;
  DWORD                    DhcpServerAddress;
  DWORD                    DomainName;
  DWORD                    EnableDhcp;
  DWORD                    OptDnsAddress;
  DWORD                    OptSecondaryDnsAddress;
  DWORD                    OptGatewayAddress;
  DWORD                    OptSpeed;
  DWORD                    NetworkCount;
  DWORD                    AddressFlags;
  DWORD                    OwnerModuleHandle;
  DWORD                    TunnelType;
  DWORD                    OwnerType;
  DWORD                    IpsecPolicyOwner;
  DWORD                    InboundPacingRate;
  DWORD                    OutboundPacingRate;
  DWORD                    AdapterState;
  DWORD                    Index;
  DWORD                    Address[4];
  DWORD                    BroadcastAddr[4];
  DWORD                    Gateway[4];
  DWORD                    CurrentSubnetMask[4];
  DWORD                    Mask[4];
  DWORD                    IpAddress[4];
  DWORD                    SubnetMask[4];
  DWORD                    DhcpServerAddress[4];
  DWORD                    GatewayList[4];
  DWORD                    DhcpServer[4];
  DWORD                    SecondaryWinsServer[4];
  DWORD                    PrimaryWinsServer[4];
  DWORD                    GatewayList[4];
  DWORD                    DhcpServer[4];
  DWORD                    DomainName[256];
  DWORD                    DnsSuffix[256];
  DWORD                    Description[256];
  DWORD                    AdapterName[256];
  DWORD                    GatewayList[4];
  DWORD                    DhcpServer[4];
  DWORD                    DomainName[256];
  DWORD                    DnsSuffix[256];
  DWORD                    Description[256];
  DWORD                    AdapterName[256];
  DWORD                    IpAddressList[4];
} IP_ADAPTER_INFO;

Note: The above is a simplified representation. The actual structure is complex and contains members for various network configurations. For a complete definition, refer to the official Windows SDK documentation.

See also