GetTcpTable 함수(iphlpapi.h)

아티클
08/24/2023

GetTcpTable 함수는 IPv4 TCP 연결 테이블을 검색합니다.

구문

IPHLPAPI_DLL_LINKAGE ULONG GetTcpTable(
  [out]     PMIB_TCPTABLE TcpTable,
  [in, out] PULONG        SizePointer,
  [in]      BOOL          Order
);

매개 변수

[out] TcpTable

TCP 연결 테이블을 MIB_TCPTABLE 구조로 수신하는 버퍼에 대한 포인터입니다.

[in, out] SizePointer

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

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

Windows Vista 이상용으로 릴리스된 Windows SDK에서 이 매개 변수의 데이터 형식은 PDWORD와 동일한 PULONG으로 변경됩니다.

[in] Order

TCP 연결 테이블을 정렬할지 여부를 지정하는 부울 값입니다. 이 매개 변수가 TRUE이면 테이블이 다음 순서로 정렬됩니다.

로컬 IP 주소
로컬 포트
원격 IP 주소
원격 포트

반환 값

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

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

반환 코드	설명
ERROR_INSUFFICIENT_BUFFER	pTcpTable 매개 변수가 가리키는 버퍼가 충분히 크지 않습니다. pdwSize 매개 변수가 가리키는 DWORD 변수에 필요한 크기가 반환됩니다. pTcpTable 매개 변수가 NULL인 경우에도 이 오류가 반환됩니다.
ERROR_INVALID_PARAMETER	pdwSize 매개 변수가 NULL이거나 GetTcpTable이 pdwSize 매개 변수가 가리키는 메모리에 쓸 수 없습니다.
ERROR_NOT_SUPPORTED	이 함수는 로컬 시스템에서 사용 중인 운영 체제에서 지원되지 않습니다.
STATUS_UNSUCCESSFUL	이 반환 코드를 받으면 함수를 다시 호출하면 일반적으로 문제를 지우고 원하는 결과를 얻을 수 있습니다. 이 반환 코드는 시스템의 부하가 높은 결과일 수 있습니다. 예를 들어 TCP 연결 테이블의 크기가 3회 연속으로 2개 이상의 추가 항목으로 변경되는 경우입니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

Windows Vista 이상용으로 릴리스된 Windows SDK에서는 GetTcpTable 함수의 반환 값이 DWORD와 동일한 ULONG 데이터 형식으로 변경됩니다.

예제

다음 예제에서는 IPv4에 대한 TCP 연결 테이블을 검색하고 각 연결의 상태를 출력합니다.

// Need to link with Iphlpapi.lib and Ws2_32.lib
#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 main()
{

    // Declare and initialize variables
    PMIB_TCPTABLE pTcpTable;
    DWORD dwSize = 0;
    DWORD dwRetVal = 0;

    char szLocalAddr[128];
    char szRemoteAddr[128];

    struct in_addr IpAddr;

    int i;

    pTcpTable = (MIB_TCPTABLE *) MALLOC(sizeof (MIB_TCPTABLE));
    if (pTcpTable == NULL) {
        printf("Error allocating memory\n");
        return 1;
    }

    dwSize = sizeof (MIB_TCPTABLE);
// Make an initial call to GetTcpTable to
// get the necessary size into the dwSize variable
    if ((dwRetVal = GetTcpTable(pTcpTable, &dwSize, TRUE)) ==
        ERROR_INSUFFICIENT_BUFFER) {
        FREE(pTcpTable);
        pTcpTable = (MIB_TCPTABLE *) MALLOC(dwSize);
        if (pTcpTable == NULL) {
            printf("Error allocating memory\n");
            return 1;
        }
    }
// Make a second call to GetTcpTable to get
// the actual data we require
    if ((dwRetVal = GetTcpTable(pTcpTable, &dwSize, TRUE)) == NO_ERROR) {
        printf("\tNumber of entries: %d\n", (int) pTcpTable->dwNumEntries);
        for (i = 0; i < (int) pTcpTable->dwNumEntries; i++) {
            IpAddr.S_un.S_addr = (u_long) pTcpTable->table[i].dwLocalAddr;
            strcpy_s(szLocalAddr, sizeof (szLocalAddr), inet_ntoa(IpAddr));
            IpAddr.S_un.S_addr = (u_long) pTcpTable->table[i].dwRemoteAddr;
            strcpy_s(szRemoteAddr, sizeof (szRemoteAddr), inet_ntoa(IpAddr));

            printf("\n\tTCP[%d] State: %ld - ", i,
                   pTcpTable->table[i].dwState);
            switch (pTcpTable->table[i].dwState) {
            case MIB_TCP_STATE_CLOSED:
                printf("CLOSED\n");
                break;
            case MIB_TCP_STATE_LISTEN:
                printf("LISTEN\n");
                break;
            case MIB_TCP_STATE_SYN_SENT:
                printf("SYN-SENT\n");
                break;
            case MIB_TCP_STATE_SYN_RCVD:
                printf("SYN-RECEIVED\n");
                break;
            case MIB_TCP_STATE_ESTAB:
                printf("ESTABLISHED\n");
                break;
            case MIB_TCP_STATE_FIN_WAIT1:
                printf("FIN-WAIT-1\n");
                break;
            case MIB_TCP_STATE_FIN_WAIT2:
                printf("FIN-WAIT-2 \n");
                break;
            case MIB_TCP_STATE_CLOSE_WAIT:
                printf("CLOSE-WAIT\n");
                break;
            case MIB_TCP_STATE_CLOSING:
                printf("CLOSING\n");
                break;
            case MIB_TCP_STATE_LAST_ACK:
                printf("LAST-ACK\n");
                break;
            case MIB_TCP_STATE_TIME_WAIT:
                printf("TIME-WAIT\n");
                break;
            case MIB_TCP_STATE_DELETE_TCB:
                printf("DELETE-TCB\n");
                break;
            default:
                printf("UNKNOWN dwState value\n");
                break;
            }
            printf("\tTCP[%d] Local Addr: %s\n", i, szLocalAddr);
            printf("\tTCP[%d] Local Port: %d \n", i,
                   ntohs((u_short)pTcpTable->table[i].dwLocalPort));
            printf("\tTCP[%d] Remote Addr: %s\n", i, szRemoteAddr);
            printf("\tTCP[%d] Remote Port: %d\n", i,
                   ntohs((u_short)pTcpTable->table[i].dwRemotePort));
        }
    } else {
        printf("\tGetTcpTable failed with %d\n", dwRetVal);
        FREE(pTcpTable);
        return 1;
    }

    if (pTcpTable != NULL) {
        FREE(pTcpTable);
        pTcpTable = NULL;
    }    

    return 0;    
}

요구 사항


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