SetPerTcpConnectionEStats 関数 (iphlpapi.h)

[アーティクル]
03/14/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構造体を除き、1 つのメンバーを持ちます。 EstatsType パラメーターが TcpConnectionEstatsBandwidth に設定されている場合、Rw パラメーターが指すTCP_ESTATS_BANDWIDTH_RW_v0構造体には、SetPerTcpConnectionEStats 関数の 1 回の呼び出しで両方の構造体メンバーが優先値に設定されている必要があります。

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) が原因で失敗する可能性もあります。この関数を含むアプリケーションが、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーによって実行された場合、 requestedExecutionLevel が requireAdministrator に設定されたマニフェストファイルでアプリケーションがマークされていない限り、この呼び出しは失敗します。 Windows Vista または Windows Server 2008 上のアプリケーションにこのマニフェストファイルがない場合、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしたユーザーは、この関数を成功させるために、拡張シェルで組み込みの Administrator (RunAs 管理者) としてアプリケーションを実行する必要があります。

Windows 10バージョン 1709 (Fall Creators Update) より前の Windows バージョンでは、SetPerTcpConnectionEStats を使用して接続の統計を無効にして再有効化できるため、統計カウンターは 0 にリセットされます。 Windows 10バージョン 1709 (Fall Creators Update) の時点では、統計が無効にされて再び有効になると、一部の統計カウンターはリセットされません。また、2 つのアプリケーションが同じ接続の統計を監視している場合、1 つのアプリケーションで統計を無効にすることで、もう一方のアプリケーションが混乱する可能性があります。このような理由から、アプリケーションでは接続に関する統計を無効にしないようにすることをお勧めします。時間の経過に伴う変更を検出するには、 GetPerTcpConnectionEStats の前回の呼び出しで読み取られたカウンター値を保存し、後続の呼び出しによって読み取られたカウンター値から減算する必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	iphlpapi.h
Library	Iphlpapi.lib
[DLL]	Iphlpapi.dll