GetPerTcpConnectionEStats 함수(iphlpapi.h)

아티클
08/24/2023

GetPerTcpConnectionEStats 함수는 IPv4 TCP 연결에 대한 확장 통계를 검색합니다.

구문

IPHLPAPI_DLL_LINKAGE ULONG GetPerTcpConnectionEStats(
        PMIB_TCPROW     Row,
        TCP_ESTATS_TYPE EstatsType,
  [out] PUCHAR          Rw,
        ULONG           RwVersion,
        ULONG           RwSize,
  [out] PUCHAR          Ros,
        ULONG           RosVersion,
        ULONG           RosSize,
  [out] PUCHAR          Rod,
        ULONG           RodVersion,
        ULONG           RodSize
);

매개 변수

Row

IPv4 TCP 연결에 대한 MIB_TCPROW 구조체에 대한 포인터입니다.

EstatsType

요청된 TCP에 대한 확장 통계 유형입니다. 이 매개 변수는 호출이 성공한 경우 Rw, Rod 및 Ros 매개 변수에 반환되는 정보의 데이터와 형식을 결정합니다.

이 매개 변수는 Tcpestats.h 헤더 파일에 정의된 TCP_ESTATS_TYPE 열거형 형식의 값 중 하나일 수 있습니다.

값	의미
TcpConnectionEstatsSynOpts	이 값은 TCP 연결에 대한 SYN 교환 정보를 요청합니다. 이 열거형 값에는 읽기 전용 정적 정보만 사용할 수 있습니다. Ros 매개 변수가 NULL이 아니고 함수가 성공하면 Ros 매개 변수가 가리키는 버퍼에 TCP_ESTATS_SYN_OPTS_ROS_v0 구조체가 포함되어야 합니다.
TcpConnectionEstatsData	이 값은 TCP 연결에 대한 확장 데이터 전송 정보를 요청합니다. 이 열거형 값에는 읽기 전용 동적 정보 및 읽기/쓰기 정보만 사용할 수 있습니다. Rw 매개 변수가 NULL이 아니고 함수가 성공하면 Rw 매개 변수가 가리키는 버퍼에 TCP_ESTATS_DATA_RW_v0 구조가 포함되어야 합니다. 이 TCP 연결에 대해 확장 데이터 전송 정보를 사용하도록 설정한 경우 Rod 매개 변수가 NULL이 아니고 함수가 성공하면 Rod 매개 변수가 가리키는 버퍼에 TCP_ESTATS_DATA_ROD_v0 구조가 포함되어야 합니다.
TcpConnectionEstatsSndCong	이 값은 TCP 연결에 대한 발신자 정체를 요청합니다. 이 열거형 값에는 세 가지 유형의 정보(읽기 전용 정적, 읽기 전용 동적 및 읽기/쓰기 정보)를 모두 사용할 수 있습니다. Rw 매개 변수가 NULL이 아니고 함수가 성공하면 Rw 매개 변수가 가리키는 버퍼에 TCP_ESTATS_SND_CONG_RW_v0 구조가 포함되어야 합니다. Ros 매개 변수가 NULL이 아니고 함수가 성공하면 Ros 매개 변수가 가리키는 버퍼에 TCP_ESTATS_SND_CONG_ROS_v0 구조체가 포함되어야 합니다. 이 TCP 연결에 대해 보낸 사람 정체 정보를 사용하도록 설정한 경우 Rod 매개 변수가 NULL이 아니고 함수가 성공하면 Rod 매개 변수가 가리키는 버퍼에 TCP_ESTATS_SND_CONG_ROD_v0 구조가 포함되어야 합니다.
TcpConnectionEstatsPath	이 값은 TCP 연결에 대한 확장 경로 측정 정보를 요청합니다. 이 열거형 값에는 읽기 전용 동적 정보 및 읽기/쓰기 정보만 사용할 수 있습니다. Rw 매개 변수가 NULL이 아니고 함수가 성공하면 Rw 매개 변수가 가리키는 버퍼에 TCP_ESTATS_PATH_RW_v0 구조가 포함되어야 합니다. 이 TCP 연결에 대해 확장 경로 측정 정보를 사용하도록 설정한 경우 Rod 매개 변수가 NULL이 아니고 함수가 성공하면 Rod 매개 변수가 가리키는 버퍼에 TCP_ESTATS_PATH_ROD_v0 구조가 포함되어야 합니다.
TcpConnectionEstatsSendBuff	이 값은 TCP 연결에 대한 확장 출력 큐 정보를 요청합니다. 이 열거형 값에는 읽기 전용 동적 정보 및 읽기/쓰기 정보만 사용할 수 있습니다. Rw 매개 변수가 NULL이 아니고 함수가 성공하면 Rw 매개 변수가 가리키는 버퍼에 TCP_ESTATS_SEND_BUFF_RW_v0 구조가 포함되어야 합니다. 이 TCP 연결에 대해 확장 출력 큐 정보를 사용하도록 설정한 경우 Rod 매개 변수가 NULL이 아니고 함수가 성공하면 Rod 매개 변수가 가리키는 버퍼에 TCP_ESTATS_SEND_BUFF_ROD_v0 구조가 포함되어야 합니다.
TcpConnectionEstatsRec	이 값은 TCP 연결에 대한 확장된 로컬 수신기 정보를 요청합니다. 이 열거형 값에는 읽기 전용 동적 정보 및 읽기/쓰기 정보만 사용할 수 있습니다. Rw 매개 변수가 NULL이 아니고 함수가 성공하면 Rw 매개 변수가 가리키는 버퍼에 TCP_ESTATS_REC_RW_v0 구조가 포함되어야 합니다. 이 TCP 연결에 확장된 로컬 수신기 정보를 사용하도록 설정한 경우 Rod 매개 변수가 NULL이 아니고 함수가 성공하면 Rod 매개 변수가 가리키는 버퍼에 TCP_ESTATS_REC_ROD_v0 구조가 포함되어야 합니다.
TcpConnectionEstatsObsRec	이 값은 TCP 연결에 대한 확장된 원격 수신기 정보를 요청합니다. 이 열거형 값에는 읽기 전용 동적 정보 및 읽기/쓰기 정보만 사용할 수 있습니다. Rw 매개 변수가 NULL이 아니고 함수가 성공하면 Rw 매개 변수가 가리키는 버퍼에 TCP_ESTATS_OBS_REC_RW_v0 구조가 포함되어야 합니다. 이 TCP 연결에 대해 확장 원격 수신기 정보를 사용하도록 설정한 경우 Rod 매개 변수가 NULL이 아니고 함수가 성공하면 Rod 매개 변수가 가리키는 버퍼에 TCP_ESTATS_OBS_REC_ROD_v0 구조가 포함되어야 합니다.
TcpConnectionEstatsBandwidth	이 값은 대역폭의 TCP 연결에 대한 대역폭 추정 통계를 요청합니다. 이 열거형 값에는 읽기 전용 동적 정보 및 읽기/쓰기 정보만 사용할 수 있습니다. Rw 매개 변수가 NULL이 아니고 함수가 성공하면 Rw 매개 변수가 가리키는 버퍼에 TCP_ESTATS_BANDWIDTH_RW_v0 구조가 포함되어야 합니다. 이 TCP 연결에 대역폭 추정 통계를 사용하도록 설정한 경우 Rod 매개 변수가 NULL이 아니고 함수가 성공하면 Rod 매개 변수가 가리키는 버퍼에 TCP_ESTATS_BANDWIDTH_ROD_v0 구조가 포함되어야 합니다.
TcpConnectionEstatsFineRtt	이 값은 TCP 연결에 대한 세분화된 RTT(왕복 시간) 예측 통계를 요청합니다. 이 열거형 값에는 읽기 전용 동적 정보 및 읽기/쓰기 정보만 사용할 수 있습니다. Rw 매개 변수가 NULL이 아니고 함수가 성공하면 Rw 매개 변수가 가리키는 버퍼에 TCP_ESTATS_FINE_RTT_RW_v0 구조가 포함되어야 합니다. 이 TCP 연결에 대해 세분화된 RTT 추정 통계를 사용하도록 설정한 경우 Rod 매개 변수가 NULL이 아니고 함수가 성공하면 Rod 매개 변수가 가리키는 버퍼에 TCP_ESTATS_FINE_RTT_ROD_v0 구조가 포함되어야 합니다.

[out] Rw

읽기/쓰기 정보를 수신할 버퍼에 대한 포인터입니다. 애플리케이션이 TCP 연결에 대한 읽기/쓰기 정보를 검색하지 않으려는 경우 이 매개 변수는 NULL 포인터일 수 있습니다.

RwVersion

요청된 읽기/쓰기 정보의 버전입니다. 현재 지원되는 값은 0 버전입니다.

RwSize

Rw 매개 변수가 가리키는 버퍼의 크기(바이트)입니다.

[out] Ros

읽기 전용 정적 정보를 수신하는 버퍼에 대한 포인터입니다. 애플리케이션이 TCP 연결에 대한 읽기 전용 정적 정보를 검색하지 않으려는 경우 이 매개 변수는 NULL 포인터일 수 있습니다.

RosVersion

요청된 읽기 전용 정적 정보의 버전입니다. 현재 지원되는 값은 0 버전입니다.

RosSize

Ros 매개 변수가 가리키는 버퍼의 크기(바이트)입니다.

[out] Rod

읽기 전용 동적 정보를 수신하는 버퍼에 대한 포인터입니다. 애플리케이션이 TCP 연결에 대한 읽기 전용 동적 정보를 검색하지 않으려는 경우 이 매개 변수는 NULL 포인터일 수 있습니다.

RodVersion

요청된 읽기 전용 동적 정보의 버전입니다. 현재 지원되는 값은 0 버전입니다.

RodSize

Rod 매개 변수가 가리키는 버퍼의 크기(바이트)입니다.

반환 값

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

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

반환 코드	설명
ERROR_INSUFFICIENT_BUFFER	함수에 전달된 버퍼가 너무 작습니다. 이 오류는 Rw, Ros 또는 Rod 매개 변수가 가리키는 버퍼가 데이터를 수신할 만큼 크지 않은 경우 반환됩니다. 이 오류는 Rw, Ros 또는 Rod 매개 변수가 가리키는 지정된 버퍼 중 하나가 NULL이지만 연결된 RwSize, RosSize 또는 RodSize에 길이가 지정된 경우에도 반환됩니다. 이 오류 값은 Windows Vista 및 Windows Server 2008에서 반환됩니다.
ERROR_INVALID_PARAMETER	매개 변수가 올바르지 않습니다. Row 매개 변수가 NULL 포인터인 경우 이 오류가 반환됩니다.
ERROR_INVALID_USER_BUFFER	제공된 사용자 버퍼가 요청된 작업에 잘못되었습니다. 이 오류는 Rw, Ros 또는 Rod 매개 변수가 가리키는 지정된 버퍼 중 하나가 NULL이지만 연결된 RwSize, RosSize 또는 RodSize에 길이가 지정된 경우 반환됩니다. 따라서 다음 조건이 충족되면 이 오류가 반환됩니다. Row 매개 변수는 NULL 포인터이고 RwSize 매개 변수는 0이 아닌 포인터입니다. Ros 매개 변수는 NULL 포인터이고 RosSize 매개 변수는 0이 아닌 포인터입니다. Rod 매개 변수는 NULL 포인터이고 RodSize 매개 변수는 0이 아닌 포인터입니다. 이 오류 값은 Windows 7 및 Windows Server 2008 R2에서 반환됩니다.
ERROR_NOT_FOUND	요청한 항목을 찾을 수 없습니다. Row 매개 변수에 지정된 TCP 연결을 찾을 수 없는 경우 이 오류가 반환됩니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. RwVersion, RosVersion 또는 RodVersion 매개 변수가 0으로 설정되지 않은 경우 이 오류가 반환됩니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

GetPerTcpConnectionEStats 함수는 Windows Vista 이상에서 정의됩니다.

GetPerTcpConnectionEStats 함수는 TCP를 사용하여 네트워크와 애플리케이션 모두에서 성능 문제를 진단하도록 설계되었습니다. 네트워크 기반 애플리케이션의 성능이 저하되면 TCP는 병목 현상이 보낸 사람, 수신자 또는 네트워크 자체에 있는지 확인할 수 있습니다. 병목 현상이 네트워크에 있는 경우 TCP는 특성에 대한 특정 정보를 제공할 수 있습니다.

GetPerTcpConnectionEStats 함수는 Row 매개 변수에 전달된 IPv4 TCP 연결에 대한 확장 통계를 검색합니다. 검색되는 확장 통계의 형식은 EstatsType 매개 변수에 지정됩니다. 이 TCP 연결에 대한 확장 통계는 이전에 EstatsType 매개 변수에서 TcpConnectionEstatsSynOpts가 전달되는 경우를 제외하고 모든 TCP_ESTATS_TYPE 값에 대해 SetPerTcpConnectionEStats 함수를 호출하여 사용하도록 설정해야 합니다.

GetTcpTable 함수는 로컬 컴퓨터에서 IPv4 TCP 연결 테이블을 검색하는 데 사용됩니다. 이 함수는 MIB_TCPROW 항목의 배열을 포함하는 MIB_TCPTABLE 구조를 반환합니다. GetPerTcpConnectionEStats 함수에 전달된 Row 매개 변수는 기존 IPv4 TCP 연결에 대한 항목이어야 합니다.

현재 지원되는 TCP 연결 통계의 유일한 버전은 버전 0입니다. 따라서 GetPerTcpConnectionEStats에 전달된 RwVersion, RosVersion 및 RodVersion 매개 변수를 0으로 설정해야 합니다.

IPv6 연결의 확장된 TCP 통계에 대한 자세한 내용은 GetPerTcp6ConnectionEStats 및 SetPerTcp6ConnectionEStats 함수를 참조하세요.

SetPerTcpConnectionEStats 함수는 관리자 그룹의 구성원으로 로그온한 사용자만 호출할 수 있습니다. Administrators 그룹의 구성원이 아닌 사용자가 SetPerTcpConnectionEStats 를 호출하면 함수 호출이 실패하고 ERROR_ACCESS_DENIED 반환됩니다. 이 함수는 Windows Vista 이상에서 UAC(사용자 계정 제어)로 인해 실패할 수도 있습니다. 이 함수를 포함하는 애플리케이션이 기본 제공 관리자가 아닌 Administrators 그룹의 구성원으로 로그온한 사용자에 의해 실행되는 경우 애플리케이션이 requestedExecutionLevel 이 requireAdministrator로 설정된 매니페스트 파일에 표시되지 않는 한 이 호출은 실패합니다. 애플리케이션에 이 매니페스트 파일이 없는 경우 기본 제공 관리자가 아닌 Administrators 그룹의 구성원으로 로그온한 사용자는 이 함수가 성공하려면 기본 제공 관리자(RunAs 관리자)로 향상된 셸에서 애플리케이션을 실행해야 합니다.

GetPerTcpConnectionEStats의 호출자는 반환된 Rw 구조체에서 EnableCollection 필드를 검사, 그렇지 않은 TRUE경우 호출자는 Ros 및 Rod 구조체의 데이터를 무시해야 합니다. EnableCollection이 로 FALSE설정된 경우 Ros 및 Rod에서 반환된 데이터는 정의되지 않습니다. 예를 들어 이 문제가 발생할 수 있는 한 가지 조건은 GetPerTcpConnectionEStats 를 사용하여 IPv4 TCP 연결에 대한 확장 통계를 검색하고 이전에 SetPerTcpConnectionEStats 를 호출하여 확장된 통계를 사용하도록 설정한 경우입니다. SetPerTcpConnectionEStats 호출이 실패하면 GetPerTcpConnectionEStats에 대한 후속 호출은 확장된 TCP 통계가 아닌 의미 없는 임의 데이터를 반환합니다. 아래 예제를 관리자 및 일반 사용자로 실행하여 해당 예제를 관찰할 수 있습니다.

예제

코드 예제는 GetPerTcp6ConnectionEStats 함수 항목의 예제 섹션을 참조하세요.

요구 사항


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