SetPerTcpConnectionEStats 函式 (iphlpapi.h)

發行項
02/28/2024

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 的零。

RwSize

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

Offset

要設定 之 Rw 參數所指向之結構中的位移，以位元組為單位。此參數目前未使用，且必須設定為零。

傳回值

如果函式成功，傳回值會NO_ERROR。

如果函式失敗，傳回值就是下列其中一個錯誤碼。

傳回碼	Description
ERROR_ACCESS_DENIED	存取遭到拒絕。此錯誤會在數種狀況下傳回：使用者缺少本機電腦上的必要系統管理許可權，或應用程式未在增強殼層中執行，因為內建系統管理員 (RunAs 系統管理員) 。
ERROR_INVALID_USER_BUFFER	提供的用戶緩衝區對要求的作業無效。如果 Row 參數為 NULL 指標，且 RwSize 參數為非零，則會傳回此錯誤。
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 連線統計數據版本是版本零。因此，傳遞至 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 群組成員身分登入的使用者呼叫。如果 SetPerTcpConnectionEStats 是由不是 Administrators 群組成員的使用者呼叫，則函式呼叫將會失敗，並 傳回ERROR_ACCESS_DENIED 。此函式也可能因為 Windows Vista 和 Windows Server 2008 上的使用者帳戶控制 (UAC) 而失敗。如果包含此函式的應用程式是由使用者以系統管理員以外的系統管理員群組成員身分登入來執行，除非應用程式已在指令清單檔中標示為 requestedExecutionLevel 設定為 requireAdministrator，否則此呼叫將會失敗。如果 Windows Vista 或 Windows Server 2008 上的應用程式缺少此指令清單檔案，則使用者以系統管理員以外的系統管理員群組成員身分登入，則必須在增強的殼層中執行應用程式，因為內建系統管理員 (RunAs 系統管理員) ，此函式才能成功。

在 Windows 10 版本 1709 (Fall Creators Update) 之前的 Windows 版本中，您可以使用 SetPerTcpConnectionEStats 來停用和重新啟用連線上的統計數據，導致任何統計數據計數器重設為零。從 Windows 10 版 1709 (Fall Creators Update) 開始，某些統計數據計數器不會在統計數據停用並重新啟用時重設。此外，如果兩個應用程式正在監視相同連線的統計數據，則一個應用程式可以藉由停用統計數據來混淆另一個應用程式。基於這些原因，我們建議您的應用程式避免停用連線的統計數據。若要偵測一段時間的變更，您應該儲存先前呼叫 GetPerTcpConnectionEStats 所讀取的計數器值，並減去後續呼叫所讀取的計數器值。

規格需求

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