GetInterfaceInfo 함수(iphlpapi.h)

아티클
08/24/2023

GetInterfaceInfo 함수는 로컬 시스템에서 IPv4를 사용하도록 설정된 네트워크 인터페이스 어댑터 목록을 가져옵니다.

구문

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

매개 변수

[out] pIfTable

어댑터 목록을 수신하는 IP_INTERFACE_INFO 구조를 지정하는 버퍼에 대한 포인터입니다. 이 버퍼는 호출자가 할당해야 합니다.

[in, out] dwOutBufLen

IP_INTERFACE_INFO 구조를 수신하기 위해 pIfTable 매개 변수가 가리키는 버퍼의 크기를 지정하는 DWORD 변수에 대한 포인터입니다. 이 크기가 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를 사용하도록 설정된 네트워크 어댑터와 관련이 있습니다. 함수는 로컬 시스템에서 IPv4를 사용하도록 설정된 네트워크 어댑터 수와 IPv4를 사용하도록 설정된 각 네트워크 어댑터에 대한 정보가 있는 IP_ADAPTER_INDEX_MAP 구조의 배열을 포함하는 pIfTable 매개 변수가 가리키는 IP_INTERFACE_INFO 구조를 반환합니다. GetInterfaceInfo에서 반환된 IP_INTERFACE_INFO 구조체에는 IP_INTERFACE_INFO 구조체의 NumAdapters 멤버가 IPv4를 사용하는 네트워크 어댑터가 사용하도록 설정되어 있지 않음을 나타내더라도 하나 이상의 IP_ADAPTER_INDEX_MAP 구조체가 포함됩니다. GetInterfaceInfo에서 반환된 IP_INTERFACE_INFO 구조체의 NumAdapters 멤버가 0이면 IP_INTERFACE_INFO 구조체에서 반환된 단일 IP_ADAPTER_INDEX_MAP 구조체의 멤버 값이 정의되지 않습니다.

GetInterfaceInfo 함수가 너무 작은 버퍼로 호출되어 IPv4 인터페이스 정보를 검색하는 경우(dwOutBufLen 매개 변수는 pIfTable 매개 변수가 가리키는 버퍼가 너무 작다는 것을 나타낸다) 함수는 ERROR_INSUFFICIENT_BUFFER 반환합니다. 필요한 크기는 dwOutBufLen 매개 변수가 가리키는 DWORD 변수에 반환됩니다.

GetInterfaceInfo 함수를 사용하는 올바른 방법은 이 함수를 두 번 호출하는 것입니다. 첫 번째 호출에서 pIfTable 매개 변수에 NULL 포인터를 전달하고 dwOutBufLen 매개 변수가 가리키는 변수에 0을 전달합니다. ERROR_INSUFFICIENT_BUFFER 호출이 실패하고 이 버퍼에 필요한 크기가 dwOutBufLen 매개 변수가 가리키는 DWORD 변수에 반환됩니다. 그런 다음 dwOutBufLen이 가리키는 값을 사용하여 필요한 크기의 버퍼를 할당할 수 있습니다. 그런 다음 , GetInterfaceInfo 함수는 pIfTable 매개 변수에 전달된 이 버퍼에 대한 포인터와 이 버퍼의 크기로 설정된 버퍼의 길이를 사용하여 두 번째로 호출할 수 있습니다.

GetAdaptersInfo 및 GetInterfaceInfo 함수는 루프백 인터페이스에 대한 정보를 반환하지 않습니다. 루프백 인터페이스에 대한 정보는 GetIpAddrTable 함수에서 반환됩니다.

Windows Vista 이상에서 IP_INTERFACE_INFO 구조체에 반환된 IP_ADAPTER_INDEX_MAP 구조체의 Name 멤버는 네트워크 인터페이스에 대한 GUID의 유니코드 문자열일 수 있습니다(문자열은 '{' 문자로 시작).

예제

다음 예제에서는 로컬 시스템에서 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
라이브러리	Iphlpapi.lib
DLL	Iphlpapi.dll