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	此值會要求 (RTT) TCP 連線的微調往返時間。此列舉值只能使用唯讀動態資訊和讀取/寫入資訊。如果 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

要求的讀取/寫入資訊版本。目前支援的值是零的版本。

RwSize

Rw參數所指向之緩衝區的大小，以位元組為單位。

[out] Ros

要接收唯讀靜態資訊的緩衝區指標。如果應用程式不想擷取 TCP 連線的唯讀靜態資訊，此參數可能是 Null 指標。

RosVersion

要求的唯讀靜態資訊版本。目前支援的值是零的版本。

RosSize

Ros參數所指向之緩衝區的大小，以位元組為單位。

[out] Rod

要接收唯讀動態資訊的緩衝區指標。如果應用程式不想擷取 TCP 連線的唯讀動態資訊，此參數可能是 Null 指標。

RodVersion

要求的唯讀動態資訊版本。目前支援的值是零的版本。

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參數為非零。 Ros參數是Null指標，而 RosSize參數為非零。 Rod 參數為Null指標，RodSize參數為非零。此錯誤值會在 Windows 7 和 Windows Server 2008 R2 上傳回。
ERROR_NOT_FOUND	找不到此要求的專案。如果找不到 Row 參數中指定的 TCP 連線，就會傳回此錯誤。
ERROR_NOT_SUPPORTED	不支援此要求。如果 RwVersion、 RosVersion或 RodVersion 參數未設定為零，就會傳回此錯誤。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

GetPerTcpConnectionEStats函式是在 Windows Vista 和更新版本上定義。

GetPerTcpConnectionEStats函式的設計目的是使用 TCP 來診斷網路和應用程式中的效能問題。如果網路型應用程式效能不佳，TCP 可以判斷瓶頸是否位於傳送者、接收者或網路本身。如果瓶頸位於網路中，TCP 可以提供其本質的特定資訊。

GetPerTcpConnectionEStats函式會擷取在 Row參數中傳遞之 IPv4 TCP 連線的擴充統計資料。擷取的擴充統計資料類型是在 EstatsType 參數中指定。除非TcpConnectionEstatsSynOpts 在 EstatsType 參數中傳遞 TcpConnectionEstatsSynOpts，否則呼叫SetPerTcpConnectionEStats函式的所有TCP_ESTATS_TYPE值，都必須啟用此 TCP 連線的擴充統計資料。

GetTcpTable函式可用來擷取本機電腦上的 IPv4 TCP 連線資料表。此函式會傳回包含MIB_TCPROW專案陣列的MIB_TCPTABLE結構。傳遞至GetPerTcpConnectionEStats函式的Row參數必須是現有 IPv4 TCP 連線的專案。

目前唯一支援的 TCP 連線統計資料版本是版本零。因此，傳遞至GetPerTcpConnectionEStats的RwVersion、RosVersion和RodVersion參數應該設定為 0。

如需 IPv6 連線上擴充 TCP 統計資料的詳細資訊，請參閱 GetPerTcp6ConnectionEStats 和 SetPerTcp6ConnectionEStats 函式。

SetPerTcpConnectionEStats函式只能由以 Administrators 群組成員身分登入的使用者呼叫。如果 SetPerTcpConnectionEStats 是由不是 Administrators 群組成員的使用者呼叫，則函式呼叫將會失敗，並 傳回ERROR_ACCESS_DENIED 。此函式也可能因為 Windows Vista 和更新版本上的使用者帳戶控制 (UAC) 而失敗。如果包含此函式的應用程式是由使用者以系統管理員以外的系統管理員群組成員身分登入來執行，除非應用程式已在資訊清單檔中標示為 requestedExecutionLevel 設定為 requireAdministrator，否則此呼叫將會失敗。如果應用程式缺少此資訊清單檔，則身為系統管理員以外的 Administrators 群組成員登入的使用者，就必須在增強殼層中執行應用程式，因為內建系統管理員 (RunAs 系統管理員) ，此函式才能成功。

GetPerTcpConnectionEStats的呼叫端應該檢查傳回的 Rw結構中的EnableCollection欄位，如果不是 TRUE ，則呼叫端應該忽略Ros和Rod結構中的資料。如果 EnableCollection 設定為 FALSE ，則 Ros 和 Rod 中傳回的資料未定義。例如，當您使用 GetPerTcpConnectionEStats 來擷取 IPv4 TCP 連線的擴充統計資料，而且您先前已呼叫 SetPerTcpConnectionEStats 來啟用擴充統計資料時，就會發生這種情況。如果 SetPerTcpConnectionEStats 呼叫失敗，則 對 GetPerTcpConnectionEStats 的後續呼叫會傳回無意義的亂數據，而不是延伸的 TCP 統計資料。您可以藉由以系統管理員和一般使用者身分執行下列範例來觀察該範例。

範例

For a code example, see the Examples section in the GetPerTcp6ConnectionEStats function topic.

需求


最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	iphlpapi.h
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll