Función SetPerTcpConnectionEStats (iphlpapi.h)
La función SetPerTcpConnectionEStats establece un valor en la información de lectura y escritura de una conexión TCP IPv4. Esta función se usa para habilitar o deshabilitar estadísticas extendidas para una conexión TCP IPv4.
Sintaxis
IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
PMIB_TCPROW Row,
TCP_ESTATS_TYPE EstatsType,
PUCHAR Rw,
ULONG RwVersion,
ULONG RwSize,
ULONG Offset
);
Parámetros
Row
Puntero a una estructura de MIB_TCPROW para una conexión TCP IPv4.
EstatsType
Tipo de estadísticas extendidas para TCP que se va a establecer. Este parámetro determina los datos y el formato de información que se espera en el parámetro Rw .
Este parámetro puede ser uno de los valores del tipo de enumeración TCP_ESTATS_TYPE definido en el archivo de encabezado Tcpestats.h .
Rw
Puntero a un búfer que contiene la información de lectura y escritura que se va a establecer. El búfer debe contener un valor de la enumeración TCP_BOOLEAN_OPTIONAL para cada miembro de estructura que especifica cómo se debe actualizar cada miembro.
RwVersion
Versión de la información de lectura y escritura que se va a establecer. Este parámetro debe establecerse en cero para Windows Vista, Windows Server 2008 y Windows 7.
RwSize
Tamaño, en bytes, del búfer al que apunta el parámetro Rw .
Offset
Desplazamiento, en bytes, al miembro de la estructura a la que apunta el parámetro Rw que se va a establecer. Este parámetro no se usa actualmente y debe establecerse en cero.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es NO_ERROR.
Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error.
| Código devuelto | Descripción |
|---|---|
|
Acceso denegado. Este error se devuelve en varias condiciones que incluyen lo siguiente: el usuario carece de los privilegios administrativos necesarios en el equipo local o la aplicación no se ejecuta en un shell mejorado como administrador integrado (administrador de RunAs). |
|
El búfer de usuario proporcionado no es válido para la operación solicitada. Este error se devuelve si el parámetro Row es un puntero NULL y el parámetro RwSize es distinto de cero. |
|
El parámetro no es correcto. Este error se devuelve si el parámetro Row es un puntero NULL . |
|
No se encontró esta entrada solicitada. Este error se devuelve si no se encontró la conexión TCP especificada en el parámetro Row . |
|
No se admite la solicitud. Este error se devuelve si rwversion o el parámetro Offset no está establecido en 0. |
|
Use FormatMessage para obtener la cadena de mensaje para el error devuelto. |
Comentarios
La función SetPerTcpConnectionEStats se define en Windows Vista y versiones posteriores.
La función SetPerTcpConnectionEStats se usa para habilitar o deshabilitar estadísticas extendidas en una conexión TCP IPv4 pasada en el parámetro Row . Las estadísticas extendidas en una conexión TCP están deshabilitadas de forma predeterminada. La función SetPerTcpConnectionEStats se usa para establecer el valor de un miembro en la información de lectura y escritura para estadísticas extendidas para una conexión TCP IPv4. El parámetro EstatsType especifica el tipo y el formato de la estructura que se va a establecer. El parámetro Rw contiene un puntero a la estructura que se pasa. Se deben especificar todos los miembros de la estructura a la que apunta el parámetro Rw .
La única versión de las estadísticas de conexión TCP admitidas actualmente es la versión cero. Por lo tanto, el parámetro RwVersion pasado a SetPerTcpConnectionEStats debe establecerse en 0.
La estructura a la que apunta el parámetro Rw pasado esta función depende del valor de enumeración pasado en el parámetro EstatsType . En la tabla siguiente se indica el tipo de estructura que se debe pasar en el parámetro Rw para cada posible tipo de parámetro EstatsType .
| EstatsType | Estructura a la que apunta 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 |
El parámetro Offset no se usa actualmente y debe establecerse en 0. Las posibles estructuras a las que apunta el parámetro Rw tienen un solo miembro, excepto la estructura TCP_ESTATS_BANDWIDTH_RW_v0 . Cuando el parámetro EstatsType se establece en TcpConnectionEstatsBandwidth, la estructura de TCP_ESTATS_BANDWIDTH_RW_v0 a la que apunta el parámetro Rw debe tener ambos miembros de estructura establecidos en los valores preferidos en una sola llamada a la función SetPerTcpConnectionEStats .
Si el parámetro RwSize se establece en 0, la función SetPerTcpConnectionEStats devuelve NO_ERROR y no realiza ningún cambio en el estado de las estadísticas extendidas.
La función GetTcpTable se usa para recuperar la tabla de conexión TCP IPv4 en el equipo local. Esta función devuelve una estructura MIB_TCPTABLE que contiene una matriz de MIB_TCPROW entradas. El parámetro Row pasado a la función SetPerTcpConnectionEStats debe ser una entrada para una conexión TCP IPv4 existente.
Una vez habilitadas las estadísticas extendidas en una conexión TCP para IPv4, las aplicaciones llaman a la función GetPerTcpConnectionEStats para recuperar estadísticas extendidas en la conexión TCP.
La función GetPerTcpConnectionEStats está diseñada para usar TCP para diagnosticar problemas de rendimiento tanto en la red como en la aplicación. Si una aplicación basada en red funciona mal, TCP puede determinar si el cuello de botella está en el remitente, el receptor o la propia red. Si el cuello de botella está en la red, TCP puede proporcionar información específica sobre su naturaleza.
Para obtener información sobre las estadísticas TCP extendidas en una conexión IPv6, consulte las funciones GetPerTcp6ConnectionEStats y SetPerTcp6ConnectionEStats .
Un usuario que inició sesión como miembro del grupo Administradores solo puede llamar a la función SetPerTcpConnectionEStats . Si un usuario que no es miembro del grupo Administradores llama a SetPerTcpConnectionEStats , se producirá un error en la llamada de función y se devolverá ERROR_ACCESS_DENIED . Esta función también puede producir un error debido al control de cuentas de usuario (UAC) en Windows Vista y Windows Server 2008. Si un usuario que ha iniciado sesión como miembro del grupo Administradores que no sea el administrador integrado ejecuta esta función, se producirá un error en esta llamada a menos que la aplicación se haya marcado en el archivo de manifiesto con un valor requestedExecutionLevel establecido en requireAdministrator. Si la aplicación en Windows Vista o Windows Server 2008 carece de este archivo de manifiesto, un usuario que inició sesión como miembro del grupo Administradores distinto del administrador integrado debe ejecutar la aplicación en un shell mejorado como administrador integrado (administrador de runas) para que esta función se realice correctamente.
En las versiones de Windows anteriores a Windows 10, versión 1709 (Fall Creators Update), puedes usar SetPerTcpConnectionEStats para deshabilitar y volver a habilitar estadísticas en una conexión, lo que hace que los contadores de estadísticas se restablezcan a cero. A partir de Windows 10, versión 1709 (Fall Creators Update), algunos contadores de estadísticas no se restablecen cuando las estadísticas se deshabilitan y se vuelven a habilitar. Además, si dos aplicaciones supervisan las estadísticas de la misma conexión, una aplicación puede confundir la otra deshabilitando las estadísticas. Por estos motivos, se recomienda que la aplicación no deshabilite las estadísticas en las conexiones. Para detectar cambios con el tiempo, debe guardar los valores de contador leídos por una llamada anterior a GetPerTcpConnectionEStats y restarlos de los leídos por una llamada posterior.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | iphlpapi.h |
| Library | Iphlpapi.lib |
| Archivo DLL | Iphlpapi.dll |