Função GetPerTcpConnectionEStats (iphlpapi.h)

Artigo
08/24/2023

A função GetPerTcpConnectionEStats recupera estatísticas estendidas para uma conexão TCP IPv4.

Sintaxe

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

Um ponteiro para uma estrutura MIB_TCPROW para uma conexão TCP IPv4.

EstatsType

O tipo de estatísticas estendidas para TCP solicitado. Esse parâmetro determina os dados e o formato das informações retornadas nos parâmetros Rw, Rod e Ros se a chamada for bem-sucedida.

Esse parâmetro pode ser um dos valores do tipo de enumeração TCP_ESTATS_TYPE definido no arquivo de cabeçalho Tcpestats.h .

Valor	Significado
TcpConnectionEstatsSynOpts	Esse valor solicita informações de troca SYN para uma conexão TCP. Somente informações estáticas somente leitura estão disponíveis para esse valor de enumeração. Se o parâmetro Ros não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Ros deverá conter uma estrutura de TCP_ESTATS_SYN_OPTS_ROS_v0 .
TcpConnectionEstatsData	Esse valor solicita informações de transferência de dados estendidas para uma conexão TCP. Somente informações dinâmicas somente leitura e informações de leitura/gravação estão disponíveis para esse valor de enumeração. Se o parâmetro Rw não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Rw deverá conter uma estrutura TCP_ESTATS_DATA_RW_v0 . Se as informações de transferência de dados estendidas foram habilitadas para essa conexão TCP, o parâmetro Rod não era NULL e a função é bem-sucedida, o buffer apontado pelo parâmetro Rod deve conter uma estrutura TCP_ESTATS_DATA_ROD_v0 .
TcpConnectionEstatsSndCong	Esse valor solicita o congestionamento do remetente para uma conexão TCP. Todos os três tipos de informações (somente leitura estático, dinâmico somente leitura e informações de leitura/gravação) estão disponíveis para esse valor de enumeração. Se o parâmetro Rw não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Rw deverá conter uma estrutura TCP_ESTATS_SND_CONG_RW_v0 . Se o parâmetro Ros não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Ros deverá conter uma estrutura TCP_ESTATS_SND_CONG_ROS_v0 . Se as informações de congestionamento do remetente foram habilitadas para essa conexão TCP, o parâmetro Rod não era NULL e a função é bem-sucedida, o buffer apontado pelo parâmetro Rod deve conter uma estrutura TCP_ESTATS_SND_CONG_ROD_v0 .
TcpConnectionEstatsPath	Esse valor solicita informações de medição de caminho estendido para uma conexão TCP. Somente informações dinâmicas somente leitura e informações de leitura/gravação estão disponíveis para esse valor de enumeração. Se o parâmetro Rw não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Rw deverá conter uma estrutura TCP_ESTATS_PATH_RW_v0 . Se as informações de medição de caminho estendido foram habilitadas para essa conexão TCP, o parâmetro Rod não era NULL e a função é bem-sucedida, o buffer apontado pelo parâmetro Rod deve conter uma estrutura TCP_ESTATS_PATH_ROD_v0 .
TcpConnectionEstatsSendBuff	Esse valor solicita informações estendidas de enfileiramento de saída para uma conexão TCP. Somente informações dinâmicas somente leitura e informações de leitura/gravação estão disponíveis para esse valor de enumeração. Se o parâmetro Rw não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Rw deverá conter uma estrutura TCP_ESTATS_SEND_BUFF_RW_v0 . Se as informações estendidas de enfileiramento de saída tiverem sido habilitadas para essa conexão TCP, o parâmetro Rod não era NULL e a função terá êxito, o buffer apontado pelo parâmetro Rod deverá conter uma estrutura TCP_ESTATS_SEND_BUFF_ROD_v0 .
TcpConnectionEstatsRec	Esse valor solicita informações estendidas do receptor local para uma conexão TCP. Somente informações dinâmicas somente leitura e informações de leitura/gravação estão disponíveis para esse valor de enumeração. Se o parâmetro Rw não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Rw deverá conter uma estrutura TCP_ESTATS_REC_RW_v0 . Se as informações estendidas do receptor local foram habilitadas para essa conexão TCP, o parâmetro Rod não era NULL e a função é bem-sucedida, o buffer apontado pelo parâmetro Rod deve conter uma estrutura TCP_ESTATS_REC_ROD_v0 .
TcpConnectionEstatsObsRec	Esse valor solicita informações estendidas de receptor remoto para uma conexão TCP. Somente informações dinâmicas somente leitura e informações de leitura/gravação estão disponíveis para esse valor de enumeração. Se o parâmetro Rw não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Rw deverá conter uma estrutura TCP_ESTATS_OBS_REC_RW_v0 . Se as informações estendidas do receptor remoto foram habilitadas para essa conexão TCP, o parâmetro Rod não era NULL e a função é bem-sucedida, o buffer apontado pelo parâmetro Rod deve conter uma estrutura TCP_ESTATS_OBS_REC_ROD_v0 .
TcpConnectionEstatsBandwidth	Esse valor solicita estatísticas de estimativa de largura de banda para uma conexão TCP na largura de banda. Somente informações dinâmicas somente leitura e informações de leitura/gravação estão disponíveis para esse valor de enumeração. Se o parâmetro Rw não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Rw deverá conter uma estrutura TCP_ESTATS_BANDWIDTH_RW_v0 . Se as estatísticas de estimativa de largura de banda foram habilitadas para essa conexão TCP, o parâmetro Rod não era NULL e a função é bem-sucedida, o buffer apontado pelo parâmetro Rod deve conter uma estrutura TCP_ESTATS_BANDWIDTH_ROD_v0 .
TcpConnectionEstatsFineRtt	Esse valor solicita estatísticas de estimativa de RTT (tempo de ida e volta) refinadas para uma conexão TCP. Somente informações dinâmicas somente leitura e informações de leitura/gravação estão disponíveis para esse valor de enumeração. Se o parâmetro Rw não for NULL e a função for bem-sucedida, o buffer apontado pelo parâmetro Rw deverá conter uma estrutura TCP_ESTATS_FINE_RTT_RW_v0 . Se as estatísticas de estimativa de RTT refinadas foram habilitadas para essa conexão TCP, o parâmetro Rod não era NULL e a função é bem-sucedida, o buffer apontado pelo parâmetro Rod deve conter uma estrutura TCP_ESTATS_FINE_RTT_ROD_v0 .

[out] Rw

Um ponteiro para um buffer para receber as informações de leitura/gravação. Esse parâmetro poderá ser um ponteiro NULL se um aplicativo não quiser recuperar informações de leitura/gravação para a conexão TCP.

RwVersion

A versão das informações de leitura/gravação solicitadas. O valor atual com suporte é uma versão de zero.

RwSize

O tamanho, em bytes, do buffer apontado pelo parâmetro Rw .

[out] Ros

Um ponteiro para um buffer para receber informações estáticas somente leitura. Esse parâmetro poderá ser um ponteiro NULL se um aplicativo não quiser recuperar informações estáticas somente leitura para a conexão TCP.

RosVersion

A versão das informações estáticas somente leitura solicitadas. O valor atual com suporte é uma versão de zero.

RosSize

O tamanho, em bytes, do buffer apontado pelo parâmetro Ros .

[out] Rod

Um ponteiro para um buffer para receber informações dinâmicas somente leitura. Esse parâmetro poderá ser um ponteiro NULL se um aplicativo não quiser recuperar informações dinâmicas somente leitura para a conexão TCP.

RodVersion

A versão das informações dinâmicas somente leitura solicitadas. O valor atual com suporte é uma versão de zero.

RodSize

O tamanho, em bytes, do buffer apontado pelo parâmetro Rod .

Valor retornado

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos códigos de erro a seguir.

Código de retorno	Descrição
ERROR_INSUFFICIENT_BUFFER	Um buffer passado para uma função é muito pequeno. Esse erro será retornado se o buffer apontado pelos parâmetros Rw, Ros ou Rod não for grande o suficiente para receber os dados. Esse erro também retornará se um dos buffers indicados pelos parâmetros Rw, Ros ou Rod for NULL, mas um comprimento tiver sido especificado no RwSize, RosSize ou RodSize associado. Esse valor de erro é retornado no Windows Vista e no Windows Server 2008.
ERROR_INVALID_PARAMETER	O parâmetro está incorreto. Esse erro será retornado se o parâmetro Row for um ponteiro NULL .
ERROR_INVALID_USER_BUFFER	O buffer de usuário fornecido não é válido para a operação solicitada. Esse erro será retornado se um dos buffers indicados pelos parâmetros Rw, Ros ou Rod for NULL, mas um comprimento tiver sido especificado no RwSize, RosSize ou RodSize associado. Como resultado, esse erro será retornado se qualquer uma das seguintes condições for atendida: O parâmetro Row é um ponteiro NULL e o parâmetro RwSize é diferente de zero. O parâmetro Ros é um ponteiro NULL e o parâmetro RosSize é diferente de zero. O parâmetro Rod é um ponteiro NULL e o parâmetro RodSize é diferente de zero. Esse valor de erro é retornado no Windows 7 e no Windows Server 2008 R2.
ERROR_NOT_FOUND	Essa entrada solicitada não foi encontrada. Esse erro será retornado se a conexão TCP especificada no parâmetro Row não puder ser encontrada.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se o parâmetro RwVersion, RosVersion ou RodVersion não estiver definido como zero.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função GetPerTcpConnectionEStats é definida no Windows Vista e posterior.

A função GetPerTcpConnectionEStats foi projetada para usar o TCP para diagnosticar problemas de desempenho na rede e no aplicativo. Se um aplicativo baseado em rede estiver com um desempenho ruim, o TCP poderá determinar se o gargalo está no remetente, no receptor ou na própria rede. Se o gargalo estiver na rede, o TCP poderá fornecer informações específicas sobre sua natureza.

A função GetPerTcpConnectionEStats recupera estatísticas estendidas para a conexão TCP IPv4 passada no parâmetro Row . O tipo de estatísticas estendidas recuperadas é especificado no parâmetro EstatsType . Estatísticas estendidas nessa conexão TCP devem ter sido habilitadas anteriormente por chamadas para a função SetPerTcpConnectionEStats para todos os valores de TCP_ESTATS_TYPE , exceto quando TcpConnectionEstatsSynOpts é passado no parâmetro EstatsType .

A função GetTcpTable é usada para recuperar a tabela de conexões TCP IPv4 no computador local. Essa função retorna uma estrutura MIB_TCPTABLE que contém uma matriz de entradas de MIB_TCPROW . O parâmetro Row passado para a função GetPerTcpConnectionEStats deve ser uma entrada para uma conexão TCP IPv4 existente.

A única versão das estatísticas de conexão TCP atualmente com suporte é a versão zero. Portanto, os parâmetros RwVersion, RosVersion e RodVersion passados para GetPerTcpConnectionEStats devem ser definidos como 0.

Para obter informações sobre estatísticas TCP estendidas em uma conexão IPv6, consulte as funções GetPerTcp6ConnectionEStats e SetPerTcp6ConnectionEStats .

A função SetPerTcpConnectionEStats só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se SetPerTcpConnectionEStats for chamado por um usuário que não é membro do grupo Administradores, a chamada de função falhará e ERROR_ACCESS_DENIED será retornado. Essa função também pode falhar devido ao UAC (controle de conta de usuário) no Windows Vista e posterior. Se um aplicativo que contém essa função for executado por um usuário conectado como membro do grupo Administradores diferente do Administrador interno, essa chamada falhará, a menos que o aplicativo tenha sido marcado no arquivo de manifesto com um requestedExecutionLevel definido para exigirAdministrator. Se o aplicativo não tiver esse arquivo de manifesto, um usuário conectado como membro do grupo Administradores diferente do Administrador interno deverá executar o aplicativo em um shell aprimorado como administrador interno (administrador RunAs) para que essa função tenha êxito.

O chamador de GetPerTcpConnectionEStats deve marcar o campo EnableCollection no struct Rw retornado e, se não TRUEfor , o chamador deverá ignorar os dados nos structs Ros e Rod. Se EnableCollection estiver definido como FALSE, os dados retornados em Ros e Rod serão indefinidos. Por exemplo, uma condição sob a qual isso pode acontecer é quando você está usando GetPerTcpConnectionEStats para recuperar estatísticas estendidas para uma conexão TCP IPv4 e você já chamou SetPerTcpConnectionEStats para habilitar estatísticas estendidas . Se a chamada SetPerTcpConnectionEStats falhar, as chamadas subsequentes para GetPerTcpConnectionEStats retornarão dados aleatórios sem sentido e não serão estatísticas TCP estendidas. Você pode observar esse exemplo executando o exemplo abaixo como administrador e como um usuário normal.

Exemplos

Para obter um exemplo de código, consulte a seção Exemplos no tópico da função GetPerTcp6ConnectionEStats .

Requisitos


Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	iphlpapi.h
Biblioteca	Iphlpapi.lib
DLL	Iphlpapi.dll