GetIpAddrTable 함수(iphlpapi.h)

아티클
08/24/2023

GetIpAddrTable 함수는 인터페이스-IPv4 주소 매핑 테이블을 검색합니다.

구문

IPHLPAPI_DLL_LINKAGE DWORD GetIpAddrTable(
  [out]     PMIB_IPADDRTABLE pIpAddrTable,
  [in, out] PULONG           pdwSize,
  [in]      BOOL             bOrder
);

매개 변수

[out] pIpAddrTable

인터페이스-IPv4 주소 매핑 테이블을 MIB_IPADDRTABLE 구조로 수신하는 버퍼에 대한 포인터입니다.

[in, out] pdwSize

입력 시 pIpAddrTable 매개 변수가 가리키는 버퍼의 크기(바이트)를 지정합니다.

출력에서 버퍼가 반환된 매핑 테이블을 보유할 만큼 충분히 크지 않은 경우 함수는 이 매개 변수를 필요한 버퍼 크기(바이트)와 동일하게 설정합니다.

[in] bOrder

이 매개 변수가 TRUE이면 반환된 매핑 테이블이 IPv4 주소별로 오름차순으로 정렬됩니다. 정렬은 네트워크 바이트 순서로 수행됩니다. 예를 들어 10.0.0.255는 10.0.1.0 바로 앞에 옵니다.

반환 값

함수가 성공하면 반환 값이 NO_ERROR.

함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.

반환 코드	설명
ERROR_INSUFFICIENT_BUFFER	pIpAddrTable 매개 변수가 가리키는 버퍼가 충분히 크지 않습니다. 필요한 크기는 pdwSize 매개 변수가 가리키는 DWORD 변수에 반환됩니다.
ERROR_INVALID_PARAMETER	pdwSize 매개 변수가 NULL이거나 GetIpAddrTable이 pdwSize 매개 변수가 가리키는 메모리에 쓸 수 없습니다.
ERROR_NOT_SUPPORTED	이 함수는 로컬 시스템에서 사용 중인 운영 체제에서 지원되지 않습니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

GetIpAddrTable 함수는 로컬 컴퓨터에서 인터페이스-IPv4 주소 매핑 테이블을 검색하고 이 정보를 MIB_IPADDRTABLE 구조로 반환합니다.

GetIpAddrTable 함수에서 반환된 IPv4 주소는 로컬 컴퓨터의 네트워크 인터페이스 상태 영향을 받습니다. NIC(네트워크 인터페이스 카드) 및 특정 PnP 이벤트를 수동으로 다시 설정하면 IP 주소가 제거되거나 변경될 수 있습니다.

Windows Server 2003 및 Windows XP에서 GetIpAddrTable 함수에서 반환된 IPv4 주소는 DisableMediaSense 함수를 호출하여 로컬 컴퓨터에서 TCP/IP 스택의 미디어 감지 기능을 사용하지 않도록 설정한 경우에도 영향을 받습니다. 미디어 감지를 사용하지 않도록 설정한 경우 GetIpAddrTable 함수는 연결이 끊긴 인터페이스와 연결된 IPv4 주소를 반환할 수 있습니다. 연결이 끊긴 인터페이스에 대한 이러한 Ipv4 주소는 사용할 수 없습니다.

Windows Server 2008 및 Windows Vista에서 GetIpAddrTable 함수에서 반환된 IPv4 주소는 로컬 컴퓨터의 TCP/IP 스택에 대한 미디어 감지 기능의 영향을 받지 않습니다. GetIpAddrTable 함수는 유효한 IPv4 주소만 반환합니다.

Windows XP에서 사용할 수 있는 GetAdaptersAddresses 함수를 사용하여 IPv6 및 IPv4 주소와 인터페이스 정보를 모두 검색할 수 있습니다.

GetIpAddrTable 함수에서 반환하는 MIB_IPADDRTABLE 구조체에는 dwNumEntries 멤버와 테이블 멤버의 첫 번째 MIB_IPADDRROW 배열 항목 간의 맞춤을 위한 안쪽 여백이 포함될 수 있습니다. 정렬을 위한 안쪽 여백은 테이블 멤버의 MIB_IPADDRROW 배열 항목 사이에도 있을 수 있습니다. MIB_IPADDRROW 배열 항목에 대한 액세스는 패딩이 있을 수 있다고 가정해야 합니다.

Windows Vista 이상용으로 릴리스된 Microsoft SDK(Windows 소프트웨어 개발 키트)에서 헤더 파일의 organization 변경되었으며 MIB_IPADDRROWIprtrmib.h 헤더 파일이 아닌 Ipmib.h 헤더 파일에 정의되어 있습니다. Ipmib.h 헤더 파일은 Iphlpapi.h 헤더 파일에 자동으로 포함되는 Iprtrmib.h에 자동으로 포함됩니다. Ipmib.h 및 Iprtrmib.h 헤더 파일을 직접 사용하면 안 됩니다.

예제

다음 예제에서는 IP 주소 테이블을 검색한 다음 테이블에 있는 IP 주소 항목의 일부 멤버를 인쇄합니다.

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

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

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

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

int __cdecl main()
{

    int i;
    
    /* Variables used by GetIpAddrTable */
    PMIB_IPADDRTABLE pIPAddrTable;
    DWORD dwSize = 0;
    DWORD dwRetVal = 0;
    IN_ADDR IPAddr;

    /* Variables used to return error message */
    LPVOID lpMsgBuf;

    // Before calling AddIPAddress we use GetIpAddrTable to get
    // an adapter to which we can add the IP.
    pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(sizeof (MIB_IPADDRTABLE));

    if (pIPAddrTable) {
        // Make an initial call to GetIpAddrTable to get the
        // necessary size into the dwSize variable
        if (GetIpAddrTable(pIPAddrTable, &dwSize, 0) ==
            ERROR_INSUFFICIENT_BUFFER) {
            FREE(pIPAddrTable);
            pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(dwSize);

        }
        if (pIPAddrTable == NULL) {
            printf("Memory allocation failed for GetIpAddrTable\n");
            exit(1);
        }
    }
    // Make a second call to GetIpAddrTable to get the
    // actual data we want
    if ( (dwRetVal = GetIpAddrTable( pIPAddrTable, &dwSize, 0 )) != NO_ERROR ) { 
        printf("GetIpAddrTable failed with error %d\n", dwRetVal);
        if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, dwRetVal, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),       // Default language
                          (LPTSTR) & lpMsgBuf, 0, NULL)) {
            printf("\tError: %s", lpMsgBuf);
            LocalFree(lpMsgBuf);
        }
        exit(1);
    }

    printf("\tNum Entries: %ld\n", pIPAddrTable->dwNumEntries);
    for (i=0; i < (int) pIPAddrTable->dwNumEntries; i++) {
        printf("\n\tInterface Index[%d]:\t%ld\n", i, pIPAddrTable->table[i].dwIndex);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwAddr;
        printf("\tIP Address[%d]:     \t%s\n", i, inet_ntoa(IPAddr) );
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwMask;
        printf("\tSubnet Mask[%d]:    \t%s\n", i, inet_ntoa(IPAddr) );
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwBCastAddr;
        printf("\tBroadCast[%d]:      \t%s (%ld%)\n", i, inet_ntoa(IPAddr), pIPAddrTable->table[i].dwBCastAddr);
        printf("\tReassembly size[%d]:\t%ld\n", i, pIPAddrTable->table[i].dwReasmSize);
        printf("\tType and State[%d]:", i);
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_PRIMARY)
            printf("\tPrimary IP Address");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DYNAMIC)
            printf("\tDynamic IP Address");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DISCONNECTED)
            printf("\tAddress is on disconnected interface");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DELETED)
            printf("\tAddress is being deleted");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_TRANSIENT)
            printf("\tTransient address");
        printf("\n");
    }

    if (pIPAddrTable) {
        FREE(pIPAddrTable);
        pIPAddrTable = NULL;
    }

    exit(0);
}

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	iphlpapi.h
라이브러리	Iphlpapi.lib
DLL	Iphlpapi.dll