SetPerTcpConnectionEStats 함수(iphlpapi.h)

아티클
08/24/2023

SetPerTcpConnectionEStats 함수는 IPv4 TCP 연결에 대한 읽기/쓰기 정보의 값을 설정합니다. 이 함수는 IPv4 TCP 연결에 대한 확장 통계를 사용하거나 사용하지 않도록 설정하는 데 사용됩니다.

구문

IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
  PMIB_TCPROW     Row,
  TCP_ESTATS_TYPE EstatsType,
  PUCHAR          Rw,
  ULONG           RwVersion,
  ULONG           RwSize,
  ULONG           Offset
);

매개 변수

Row

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

EstatsType

설정할 TCP에 대한 확장 통계 유형입니다. 이 매개 변수는 Rw 매개 변수에 필요한 정보의 데이터와 형식을 결정합니다.

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

Rw

설정할 읽기/쓰기 정보가 포함된 버퍼에 대한 포인터입니다. 버퍼에는 각 멤버를 업데이트하는 방법을 지정하는 각 구조체 멤버에 대한 TCP_BOOLEAN_OPTIONAL 열거형의 값이 포함되어야 합니다.

RwVersion

설정할 읽기/쓰기 정보의 버전입니다. 이 매개 변수는 Windows Vista, Windows Server 2008 및 Windows 7에 대해 0으로 설정해야 합니다.

RwSize

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

Offset

설정할 Rw 매개 변수가 가리키는 구조체의 멤버에 대한 오프셋(바이트)입니다. 이 매개 변수는 현재 사용되지 않으며 0으로 설정해야 합니다.

반환 값

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

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

반환 코드	설명
ERROR_ACCESS_DENIED	액세스가 거부되었습니다. 이 오류는 사용자가 로컬 컴퓨터에서 필요한 관리 권한이 없거나 애플리케이션이 기본 제공 관리자(RunAs 관리자)로 향상된 셸에서 실행되고 있지 않음을 포함하는 여러 조건에서 반환됩니다.
ERROR_INVALID_USER_BUFFER	제공된 사용자 버퍼가 요청된 작업에 잘못되었습니다. Row 매개 변수가 NULL 포인터이고 RwSize 매개 변수가 0이 아닌 경우 이 오류가 반환됩니다.
ERROR_INVALID_PARAMETER	매개 변수가 올바르지 않습니다. Row 매개 변수가 NULL 포인터인 경우 이 오류가 반환됩니다.
ERROR_NOT_FOUND	요청한 항목을 찾을 수 없습니다. 이 오류는 Row 매개 변수에 지정된 TCP 연결을 찾을 수 없는 경우 반환됩니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. RwVersion 또는 Offset 매개 변수가 0으로 설정되지 않은 경우 이 오류가 반환됩니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

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

SetPerTcpConnectionEStats 함수는 Row 매개 변수에 전달된 IPv4 TCP 연결에서 확장된 통계를 사용하거나 사용하지 않도록 설정하는 데 사용됩니다. TCP 연결에 대한 확장 통계는 기본적으로 사용하지 않도록 설정됩니다. SetPerTcpConnectionEStats 함수는 IPv4 TCP 연결에 대한 확장 통계에 대한 읽기/쓰기 정보의 멤버 값을 설정하는 데 사용됩니다. 설정할 구조체의 형식과 형식은 EstatsType 매개 변수에 의해 지정됩니다. Rw 매개 변수에는 전달되는 구조체에 대한 포인터가 포함되어 있습니다. Rw 매개 변수가 가리키는 구조체의 모든 멤버를 지정해야 합니다.

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

이 함수를 전달한 Rw 매개 변수가 가리키는 구조체는 EstatsType 매개 변수에 전달된 열거형 값에 따라 달라집니다. 아래 표는 가능한 각 EstatsType 매개 변수 형식에 대해 Rw 매개 변수에 전달되어야 하는 구조체 형식을 나타냅니다.

EstatsType	Rw가 가리키는 구조체
TcpConnectionEstatsData	TCP_ESTATS_DATA_RW_v0
TcpConnectionEstatsSndCong	TCP_ESTATS_SND_CONG_RW_v0
TcpConnectionEstatsPath	TCP_ESTATS_PATH_RW_v0
TcpConnectionEstatsSendBuff	TCP_ESTATS_SEND_BUFF_RW_v0
TcpConnectionEstatsRec	TCP_ESTATS_REC_RW_v0
TcpConnectionEstatsObsRec	TCP_ESTATS_OBS_REC_RW_v0
TcpConnectionEstatsBandwidth	TCP_ESTATS_BANDWIDTH_RW_v0
TcpConnectionEstatsFineRtt	TCP_ESTATS_FINE_RTT_RW_v0

Offset 매개 변수는 현재 사용되지 않으며 0으로 설정해야 합니다. Rw 매개 변수가 가리키는 가능한 구조체에는 모두 TCP_ESTATS_BANDWIDTH_RW_v0 구조체를 제외한 단일 멤버가 있습니다. EstatsType 매개 변수가 TcpConnectionEstatsBandwidth로 설정된 경우 Rw 매개 변수가 가리키는 TCP_ESTATS_BANDWIDTH_RW_v0 구조체에는 SetPerTcpConnectionEStats 함수에 대한 단일 호출에서 두 구조체 멤버가 모두 기본값으로 설정되어야 합니다.

RwSize 매개 변수가 0으로 설정된 경우 SetPerTcpConnectionEStats 함수는 NO_ERROR 반환하고 확장된 통계 상태 변경하지 않습니다.

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

IPv4에 대한 TCP 연결에서 확장 통계를 사용하도록 설정하면 애플리케이션은 GetPerTcpConnectionEStats 함수를 호출하여 TCP 연결에 대한 확장된 통계를 검색합니다.

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

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

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

Windows 10 이전의 Windows 버전 1709(Fall Creators Update)에서는 SetPerTcpConnectionEStats를 사용하여 연결에서 통계를 사용하지 않도록 설정하고 다시 활성화하여 통계 카운터를 0으로 다시 설정할 수 있습니다. Windows 10 버전 1709(Fall Creators Update)를 기준으로 통계가 비활성화되고 다시 활성화되면 일부 통계 카운터가 다시 설정되지 않습니다. 또한 두 애플리케이션이 동일한 연결에 대한 통계를 모니터링하는 경우 한 애플리케이션은 통계를 사용하지 않도록 설정하여 다른 애플리케이션을 혼동할 수 있습니다. 이러한 이유로 애플리케이션은 연결에 대한 통계를 사용하지 않도록 설정하는 것을 자제하는 것이 좋습니다. 시간이 지남에 따라 변경 내용을 검색하려면 GetPerTcpConnectionEStats에 대한 이전 호출에서 읽은 카운터 값을 저장하고 후속 호출에서 읽은 값에서 빼야 합니다.

요구 사항

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