SetPerTcpConnectionEStats (Compact 2013)

  • [アーティクル]

3/26/2014

This function sets a value in the read/write information for an IPv4 TCP connection. The function is used to enable or disable extended statistics for an IPv4 TCP connection.

Syntax

ULONG WINAPI SetPerTcpConnectionEStats(
    PMIB_TCP6ROW Row,
    TCP_ESTATS_TYPE EstatsType,
    PUCHAR Rw,
    ULONG RwVersion,
    ULONG RwSize,
    ULONG Offset
);

Parameters

  • Row
    A pointer to a MIB_TCPROW structure for an IPv4 TCP connection.

  • EstatsType
    The type of extended statistics for TCP to set. This parameter determines the data and format of information that is expected in the Rw parameter.

    This parameter can be one of the values from the TCP_ESTATS_TYPE enumeration type that is defined in the Tcpestats.h header file.

  • Rw
    A pointer to a buffer that contains the read/write information to set. The buffer should contain a value from the TCP_BOOLEAN_OPTIONAL enumeration for each structure member that specifies how each member should be updated.
  • RwVersion
    The version of the read/write information to be set.
  • RwSize
    The size, in bytes, of the buffer pointed to by Rw parameter.
  • Offset
    The offset, in bytes, to the member in the structure pointed to by the Rw parameter to be set.

Return Value

Return code

Description

NO_ERROR

The function succeeds.

ERROR_ACCESS_DENIED

Access is denied. This error is returned under several conditions that include the following: the user lacks the required administrative credentials on the local device or the application is not running in an enhanced shell as the built-in Administrator (RunAs administrator).

ERROR_INVALID_PARAMETER

The parameter is incorrect. This error is returned if the Row parameter is a NULL pointer.

ERROR_NOT_FOUND

This requested entry was not found. This error is returned if the TCP connection specified in the Row parameter could not be found.

Other

Use FormatMessage to obtain the message string for the returned error.

Remarks

The SetPerTcpConnectionEStats function is used to set the value of a member in the read/write information for extended statistics for an IPv4 TCP connection. The SetPerTcpConnectionEStats function can only set the value of a single DWORD member in a structure at a time. The type and format of the structure to be set is specified by the EstatsType parameter. The Rw parameter contains a pointer to the structure being passed. The member to set in this structure is specified by the Offset parameter. So this function may have to be called multiple times if more than a single member in a structure has to be set.

The only version of TCP connection statistics currently supported is version zero. So the RwVersion parameter that is passed to SetPerTcpConnectionEStats should be set to 0.

The structure pointed to by the Rw parameter that is passed this function depends on the enumeration value that is passed in the EstatsType parameter. The following table below indicates the structure type that should be passed in the Rw parameter for each possible EstatsType parameter type.

EstatsType

Structure pointed to by 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

The SetPerTcpConnectionEStats function is used to enable or disable extended statistics on an IPv4 TCP connection passed in the Row parameter. Extended statistics on a TCP connection are disabled by default.

The GetTcpTable function is used to retrieve the IPv4 TCP connection table on the local device. This function returns a MIB_TCPTABLE structure that contain an array of MIB_TCPROW entries. The Row parameter that is passed to the SetPerTcpConnectionEStats function must be an entry for an existing IPv4 TCP connection.

When extended statistics are enabled on a TCP connection for IPv4, applications call the GetPerTcpConnectionEStats function to retrieve extended statistics on the TCP connection.

The GetPerTcpConnectionEStats function is designed to use TCP to diagnose performance problems in both the network and the application. If a network based application is performing poorly, TCP can determine whether the bottleneck is in the sender, the receiver or the network itself. If the bottleneck is in the network, TCP can provide specific information about its nature.

For information on extended TCP statistics on an IPv6 connection, see the GetPerTcp6ConnectionEStats and SetPerTcp6ConnectionEStats functions.

The SetPerTcpConnectionEStats function can only be called by a user logged on as a member of the Administrators group. If SetPerTcpConnectionEStats is called by a user who is not a member of the Administrators group, the function call will fail and ERROR_ACCESS_DENIED is returned.

See Also

Reference

IP Helper Functions
GetPerTcp6ConnectionEStats
GetPerTcpConnectionEStats
GetTcpTable
MIB_TCPROW
SetPerTcp6ConnectionEStats
TCP_BOOLEAN_OPTIONAL
TCP_ESTATS_BANDWIDTH_RW_v0
TCP_ESTATS_DATA_RW_v0
TCP_ESTATS_FINE_RTT_RW_v0
TCP_ESTATS_OBS_REC_RW_v0
TCP_ESTATS_PATH_RW_v0
TCP_ESTATS_REC_RW_v0
TCP_ESTATS_SEND_BUFF_RW_v0
TCP_ESTATS_SND_CONG_RW_v0
TCP_ESTATS_TYPE