getInterfaceInfo 函数 (iphlpapi.h)

项目
08/24/2023

GetInterfaceInfo 函数获取本地系统上启用了 IPv4 的网络接口适配器的列表。

语法

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

parameters

[out] pIfTable

指向缓冲区的指针，该缓冲区指定接收适配器列表的 IP_INTERFACE_INFO 结构。此缓冲区必须由调用方分配。

[in, out] dwOutBufLen

指向 DWORD 变量的指针，该变量指定 pIfTable 参数指向的缓冲区的大小，以接收 IP_INTERFACE_INFO 结构。如果此大小不足以保存 IPv4 接口信息， 则 GetInterfaceInfo 会用所需的大小填充此变量，并返回 ERROR_INSUFFICIENT_BUFFER错误代码。

返回值

如果函数成功，则返回值 NO_ERROR。

如果函数失败，则返回值为以下错误代码之一。

返回代码	说明
ERROR_INSUFFICIENT_BUFFER	用于接收 IPv4 适配器信息的缓冲区太小。如果 dwOutBufLen 参数指示 pIfTable 参数指向的缓冲区太小，无法检索 IPv4 接口信息，则返回此值。所需大小在 dwOutBufLen 参数指向的 DWORD 变量中返回。
ERROR_INVALID_PARAMETER	向该函数传递了无效参数。如果 dwOutBufLen 参数为 NULL，或者 GetInterfaceInfo 无法写入 dwOutBufLen 参数指向的内存，则返回此错误。
ERROR_NO_DATA	本地系统上没有为 IPv4 启用网络适配器。如果禁用本地系统上的所有网络适配器，也会返回此值。
ERROR_NOT_SUPPORTED	本地系统上正在使用的操作系统不支持此函数。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

GetInterfaceInfo 函数特定于启用了 IPv4 的网络适配器。该函数返回 pIfTable 参数指向的IP_INTERFACE_INFO结构，该结构包含本地系统上启用了 IPv4 的网络适配器的数量，以及一组IP_ADAPTER_INDEX_MAP结构，其中包含每个启用了 IPv4 的网络适配器上的信息。 GetInterfaceInfo 返回的 IP_INTERFACE_INFO 结构至少包含一个 IP_ADAPTER_INDEX_MAP 结构，即使 IP_INTERFACE_INFO 结构的 NumAdapters 成员指示未启用具有 IPv4 的网络适配器。当 GetInterfaceInfo 返回的 IP_INTERFACE_INFO 结构的 NumAdapters 成员为零时，IP_INTERFACE_INFO 结构中返回的单个IP_ADAPTER_INDEX_MAP结构的成员的值是不确定的。

如果调用 GetInterfaceInfo 函数的缓冲区太小，无法检索 IPv4 接口信息 (dwOutBufLen 参数指示 pIfTable 参数指向的缓冲区太小) ，则函数返回 ERROR_INSUFFICIENT_BUFFER。所需大小在 dwOutBufLen 参数指向的 DWORD 变量中返回。

使用 GetInterfaceInfo 函数的正确方法是调用此函数两次。在第一次调用中，在 pIfTable 参数中传递 NULL 指针，在 dwOutBufLen 参数指向的变量中传递零。调用将失败并ERROR_INSUFFICIENT_BUFFER，并且 dwOutBufLen 参数指向的 DWORD 变量中返回此缓冲区的所需大小。然后，可以使用 dwOutBufLen 指向的值分配所需大小的缓冲区。然后，可以使用 pIfTable 参数中传递的指向此缓冲区的指针以及设置为此缓冲区大小的缓冲区长度，再次调用 GetInterfaceInfo 函数。

GetAdaptersInfo 和 GetInterfaceInfo 函数不返回有关环回接口的信息。有关环回接口的信息由 GetIpAddrTable 函数返回。

在 Windows Vista 及更高版本中，IP_INTERFACE_INFO 结构中返回的 IP_ADAPTER_INDEX_MAP 结构的 Name 成员可能是网络接口的 GUID 的 Unicode 字符串， (字符串以“{”字符) 开头。

示例

以下示例检索本地系统上启用了 IPv4 的网络适配器的列表，并打印第一个网络适配器的各种属性。

#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);
}

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	iphlpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll