GetInterfaceInfo function (iphlpapi.h)

The GetInterfaceInfo function obtains the list of the network interface adapters with IPv4 enabled on the local system.

Syntax

IPHLPAPI_DLL_LINKAGE DWORD GetInterfaceInfo(
  [out]     PIP_INTERFACE_INFO pIfTable,
  [in, out] PULONG             dwOutBufLen
);

Parameters

[out] pIfTable

A pointer to a buffer that specifies an IP_INTERFACE_INFO structure that receives the list of adapters. This buffer must be allocated by the caller.

[in, out] dwOutBufLen

A pointer to a DWORD variable that specifies the size of the buffer pointed to by pIfTable parameter to receive the IP_INTERFACE_INFO structure. If this size is insufficient to hold the IPv4 interface information, GetInterfaceInfo fills in this variable with the required size, and returns an error code of ERROR_INSUFFICIENT_BUFFER.

Return value

If the function succeeds, the return value is NO_ERROR.

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

Remarks

The GetInterfaceInfo function is specific to network adapters with IPv4 enabled. The function returns an IP_INTERFACE_INFO structure pointed to by the pIfTable parameter that contains the number of network adapters with IPv4 enabled on the local system and an array of IP_ADAPTER_INDEX_MAP structures with information on each network adapter with IPv4 enabled. The IP_INTERFACE_INFO structure returned by GetInterfaceInfo contains at least one IP_ADAPTER_INDEX_MAP structure even if the NumAdapters member of the IP_INTERFACE_INFO structure indicates that no network adapters with IPv4 are enabled. When the NumAdapters member of the IP_INTERFACE_INFO structure returned by GetInterfaceInfo is zero, the value of the members of the single IP_ADAPTER_INDEX_MAP structure returned in the IP_INTERFACE_INFO structure is undefined.

If the GetInterfaceInfo function is called with too small a buffer to retrieve the IPv4 interface information (the dwOutBufLen parameter indicates that the buffer pointed to by the pIfTable parameter is too small), the function returns ERROR_INSUFFICIENT_BUFFER. The required size is returned in the DWORD variable pointed to by the dwOutBufLen parameter.

The correct way to use the GetInterfaceInfo function is to call this function twice. In the first call, pass a NULL pointer in the pIfTable parameter and zero in the variable pointed to by the dwOutBufLen parameter. The call will fail with ERROR_INSUFFICIENT_BUFFER and the required size for this buffer is returned in the DWORD variable pointed to by the dwOutBufLen parameter. A buffer can then be allocated of the required size using the value pointed by the dwOutBufLen. Then the GetInterfaceInfo function can be called a second time with a pointer to this buffer passed in the pIfTable parameter and the length of the buffer set to the size of this buffer.

The GetAdaptersInfo and GetInterfaceInfo functions do not return information about the loopback interface. Information on the loopback interface is returned by the GetIpAddrTable function.

On Windows Vista and later, the Name member of the IP_ADAPTER_INDEX_MAP structure returned in the IP_INTERFACE_INFO structure may be a Unicode string of the GUID for the network interface (the string begins with the '{' character).

Examples

The following example retrieves the list of network adapters with IPv4 enabled on the local system and prints various properties of the first network adapter.

#include <winsock2.h>
#include <ws2ipdef.h>
#include <iphlpapi.h>
#include <stdio.h>

#pragma comment(lib, "iphlpapi.lib")

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x)) 
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

/* Note: could also use malloc() and free() */

int main()
{

// Declare and initialize variables
    PIP_INTERFACE_INFO pInfo = NULL;
    ULONG ulOutBufLen = 0;

    DWORD dwRetVal = 0;
    int iReturn = 1;

    int i;

// Make an initial call to GetInterfaceInfo to get
// the necessary size in the ulOutBufLen variable
    dwRetVal = GetInterfaceInfo(NULL, &ulOutBufLen);
    if (dwRetVal == ERROR_INSUFFICIENT_BUFFER) {
        pInfo = (IP_INTERFACE_INFO *) MALLOC(ulOutBufLen);
        if (pInfo == NULL) {
            printf
                ("Unable to allocate memory needed to call GetInterfaceInfo\n");
            return 1;
        }
    }
// Make a second call to GetInterfaceInfo to get
// the actual data we need
    dwRetVal = GetInterfaceInfo(pInfo, &ulOutBufLen);
    if (dwRetVal == NO_ERROR) {
        printf("Number of Adapters: %ld\n\n", pInfo->NumAdapters);
        for (i = 0; i < pInfo->NumAdapters; i++) {
            printf("Adapter Index[%d]: %ld\n", i,
                   pInfo->Adapter[i].Index);
            printf("Adapter Name[%d]: %ws\n\n", i,
                   pInfo->Adapter[i].Name);
        }
        iReturn = 0;
    } else if (dwRetVal == ERROR_NO_DATA) {
        printf
            ("There are no network adapters with IPv4 enabled on the local system\n");
        iReturn = 0;
    } else {
        printf("GetInterfaceInfo failed with error: %d\n", dwRetVal);
        iReturn = 1;
    }

    FREE(pInfo);
    return (iReturn);
}

Requirements

See also

GetAdaptersInfo

GetIpAddrTable

GetNumberOfInterfaces

IP Helper Function Reference

IP Helper Start Page

IP_ADAPTER_INDEX_MAP

IP_INTERFACE_INFO