Función GetPerTcpConnectionEStats (iphlpapi.h)

Artículo
08/24/2023

La función GetPerTcpConnectionEStats recupera estadísticas extendidas para una conexión TCP IPv4.

Sintaxis

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
);

Parámetros

Row

Puntero a una estructura de MIB_TCPROW para una conexión TCP IPv4.

EstatsType

Tipo de estadísticas extendidas para TCP solicitada. Este parámetro determina los datos y el formato de información que se devuelven en los parámetros Rw, Rod y Ros si la llamada se realiza correctamente.

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 .

Valor	Significado
TcpConnectionEstatsSynOpts	Este valor solicita información de intercambio de SYN para una conexión TCP. Solo hay información estática de solo lectura disponible para este valor de enumeración. Si el parámetro Ros no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Ros debe contener una estructura TCP_ESTATS_SYN_OPTS_ROS_v0 .
TcpConnectionEstatsData	Este valor solicita información de transferencia de datos extendida para una conexión TCP. Solo la información dinámica de solo lectura y la información de lectura y escritura están disponibles para este valor de enumeración. Si el parámetro Rw no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Rw debe contener una estructura de TCP_ESTATS_DATA_RW_v0 . Si se ha habilitado la información de transferencia de datos extendida para esta conexión TCP, el parámetro Rod no era NULL y la función se realiza correctamente, el búfer al que apunta el parámetro Rod debe contener una estructura de TCP_ESTATS_DATA_ROD_v0 .
TcpConnectionEstatsSndCong	Este valor solicita la congestión del remitente para una conexión TCP. Los tres tipos de información (información estática de solo lectura, dinámica de solo lectura y de lectura y escritura) están disponibles para este valor de enumeración. Si el parámetro Rw no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Rw debe contener una estructura de TCP_ESTATS_SND_CONG_RW_v0 . Si el parámetro Ros no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Ros debe contener una estructura de TCP_ESTATS_SND_CONG_ROS_v0 . Si la información de congestión del remitente se ha habilitado para esta conexión TCP, el parámetro Rod no era NULL y la función se realiza correctamente, el búfer al que apunta el parámetro Rod debe contener una estructura de TCP_ESTATS_SND_CONG_ROD_v0 .
TcpConnectionEstatsPath	Este valor solicita información de medición de ruta de acceso extendida para una conexión TCP. Solo la información dinámica de solo lectura y la información de lectura y escritura están disponibles para este valor de enumeración. Si el parámetro Rw no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Rw debe contener una estructura de TCP_ESTATS_PATH_RW_v0 . Si se ha habilitado la información de medición de ruta extendida para esta conexión TCP, el parámetro Rod no era NULL y la función se realiza correctamente, el búfer al que apunta el parámetro Rod debe contener una estructura de TCP_ESTATS_PATH_ROD_v0 .
TcpConnectionEstatsSendBuff	Este valor solicita información extendida de salida en cola para una conexión TCP. Solo la información dinámica de solo lectura y la información de lectura y escritura están disponibles para este valor de enumeración. Si el parámetro Rw no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Rw debe contener una estructura de TCP_ESTATS_SEND_BUFF_RW_v0 . Si se ha habilitado la información de puesta en cola extendida para esta conexión TCP, el parámetro Rod no era NULL y la función se realiza correctamente, el búfer al que apunta el parámetro Rod debe contener una estructura de TCP_ESTATS_SEND_BUFF_ROD_v0 .
TcpConnectionEstatsRec	Este valor solicita información extendida del receptor local para una conexión TCP. Solo la información dinámica de solo lectura y la información de lectura y escritura están disponibles para este valor de enumeración. Si el parámetro Rw no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Rw debe contener una estructura de TCP_ESTATS_REC_RW_v0 . Si la información extendida del receptor local se ha habilitado para esta conexión TCP, el parámetro Rod no era NULL y la función se realiza correctamente, el búfer al que apunta el parámetro Rod debe contener una estructura de TCP_ESTATS_REC_ROD_v0 .
TcpConnectionEstatsObsRec	Este valor solicita información extendida del receptor remoto para una conexión TCP. Solo la información dinámica de solo lectura y la información de lectura y escritura están disponibles para este valor de enumeración. Si el parámetro Rw no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Rw debe contener una estructura TCP_ESTATS_OBS_REC_RW_v0 . Si se ha habilitado la información extendida del receptor remoto para esta conexión TCP, el parámetro Rod no era NULL y la función se realiza correctamente, el búfer al que apunta el parámetro Rod debe contener una estructura de TCP_ESTATS_OBS_REC_ROD_v0 .
TcpConnectionEstatsBandwidth	Este valor solicita estadísticas de estimación de ancho de banda para una conexión TCP en el ancho de banda. Solo la información dinámica de solo lectura y la información de lectura y escritura están disponibles para este valor de enumeración. Si el parámetro Rw no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Rw debe contener una estructura de TCP_ESTATS_BANDWIDTH_RW_v0 . Si las estadísticas de estimación de ancho de banda se habilitaron para esta conexión TCP, el parámetro Rod no era NULL y la función se realiza correctamente, el búfer al que apunta el parámetro Rod debe contener una estructura de TCP_ESTATS_BANDWIDTH_ROD_v0 .
TcpConnectionEstatsFineRtt	Este valor solicita estadísticas de estimación de tiempo de ida y vuelta (RTT) específicas para una conexión TCP. Solo la información dinámica de solo lectura y la información de lectura y escritura están disponibles para este valor de enumeración. Si el parámetro Rw no era NULL y la función se ejecuta correctamente, el búfer al que apunta el parámetro Rw debe contener una estructura TCP_ESTATS_FINE_RTT_RW_v0 . Si las estadísticas de estimación de RTT específicas se habilitaron para esta conexión TCP, el parámetro Rod no era NULL y la función se realiza correctamente, el búfer al que apunta el parámetro Rod debe contener una estructura de TCP_ESTATS_FINE_RTT_ROD_v0 .

[out] Rw

Puntero a un búfer para recibir la información de lectura y escritura. Este parámetro puede ser un puntero NULL si una aplicación no desea recuperar información de lectura y escritura para la conexión TCP.

RwVersion

Versión de la información de lectura y escritura solicitada. El valor admitido actual es una versión de cero.

RwSize

Tamaño, en bytes, del búfer al que apunta el parámetro Rw .

[out] Ros

Puntero a un búfer para recibir información estática de solo lectura. Este parámetro puede ser un puntero NULL si una aplicación no desea recuperar información estática de solo lectura para la conexión TCP.

RosVersion

Versión de la información estática de solo lectura solicitada. El valor admitido actual es una versión de cero.

RosSize

Tamaño, en bytes, del búfer al que apunta el parámetro Ros .

[out] Rod

Puntero a un búfer para recibir información dinámica de solo lectura. Este parámetro puede ser un puntero NULL si una aplicación no desea recuperar información dinámica de solo lectura para la conexión TCP.

RodVersion

Versión de la información dinámica de solo lectura solicitada. El valor admitido actual es una versión de cero.

RodSize

Tamaño, en bytes, del búfer al que apunta el parámetro Rod .

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
ERROR_INSUFFICIENT_BUFFER	Un búfer pasado a una función es demasiado pequeño. Este error se devuelve si el búfer apuntado por los parámetros Rw, Ros o Rod no es lo suficientemente grande como para recibir los datos. Este error también se devuelve si uno de los búferes especificados a los que apuntan los parámetros Rw, Ros o Rod es NULL, pero se especificó una longitud en el RwSize, RosSize o RodSize asociado. Este valor de error se devuelve en Windows Vista y Windows Server 2008.
ERROR_INVALID_PARAMETER	El parámetro no es correcto. Este error se devuelve si el parámetro Row es un puntero NULL .
ERROR_INVALID_USER_BUFFER	El búfer de usuario proporcionado no es válido para la operación solicitada. Este error se devuelve si uno de los búferes especificados a los que apuntan los parámetros Rw, Ros o Rod es NULL, pero se especificó una longitud en el RwSize, RosSize o RodSize asociado. Como resultado, este error se devuelve si se cumple alguna de las condiciones siguientes: El parámetro Row es un puntero NULL y el parámetro RwSize es distinto de cero. El parámetro Ros es un puntero NULL y el parámetro RosSize es distinto de cero. El parámetro Rod es un puntero NULL y el parámetro RodSize es distinto de cero. Este valor de error se devuelve en Windows 7 y Windows Server 2008 R2.
ERROR_NOT_FOUND	No se encontró esta entrada solicitada. Este error se devuelve si no se encontró la conexión TCP especificada en el parámetro Row .
ERROR_NOT_SUPPORTED	No se admite la solicitud. Este error se devuelve si el parámetro RwVersion, RosVersion o RodVersion no está establecido en cero.
Otros	Use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Comentarios

La función GetPerTcpConnectionEStats se define en Windows Vista y versiones posteriores.

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.

La función GetPerTcpConnectionEStats recupera estadísticas extendidas para la conexión TCP IPv4 pasada en el parámetro Row . El tipo de estadísticas extendidas que se recupera se especifica en el parámetro EstatsType . Las estadísticas extendidas de esta conexión TCP deben haberse habilitado previamente mediante llamadas a la función SetPerTcpConnectionEStats para todos los valores de TCP_ESTATS_TYPE excepto cuando TcpConnectionEstatsSynOpts se pasa en el parámetro EstatsType .

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 GetPerTcpConnectionEStats debe ser una entrada para una conexión TCP IPv4 existente.

La única versión de las estadísticas de conexión TCP admitidas actualmente es la versión cero. Por lo tanto, los parámetros RwVersion, RosVersion y RodVersion pasados a GetPerTcpConnectionEStats deben establecerse en 0.

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 versiones posteriores. 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 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.

El autor de la llamada de GetPerTcpConnectionEStats debe comprobar el campo EnableCollection en la estructura rw devuelta y, si no TRUEes , el autor de la llamada debe omitir los datos de las estructuras Ros y Rod . Si EnableCollection se establece FALSEen , los datos devueltos en Ros y Rod no están definidos. Por ejemplo, una condición con la que esto puede ocurrir es cuando se usa GetPerTcpConnectionEStats para recuperar estadísticas extendidas para una conexión TCP IPv4 y anteriormente se ha llamado SetPerTcpConnectionEStats para habilitar las estadísticas extendidas. Si se produce un error en la llamada a SetPerTcpConnectionEStats , las llamadas posteriores a GetPerTcpConnectionEStats devolverán datos aleatorios sin significado y no las estadísticas TCP extendidas. Para observar ese ejemplo, ejecute el ejemplo siguiente como administrador y como usuario normal.

Ejemplos

Para obtener un ejemplo de código, vea la sección Ejemplos del tema de la función GetPerTcp6ConnectionEStats .

Requisitos


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