Função SetPerTcpConnectionEStats (iphlpapi.h)
A função SetPerTcpConnectionEStats define um valor nas informações de leitura/gravação de uma conexão TCP IPv4. Essa função é usada para habilitar ou desabilitar estatísticas estendidas para uma conexão TCP IPv4.
Sintaxe
IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
PMIB_TCPROW Row,
TCP_ESTATS_TYPE EstatsType,
PUCHAR Rw,
ULONG RwVersion,
ULONG RwSize,
ULONG Offset
);
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 a ser definido. Esse parâmetro determina os dados e o formato das informações esperadas no parâmetro Rw .
Esse parâmetro pode ser um dos valores do tipo de enumeração TCP_ESTATS_TYPE definido no arquivo de cabeçalho Tcpestats.h .
Rw
Um ponteiro para um buffer que contém as informações de leitura/gravação a serem definidas. O buffer deve conter um valor da enumeração TCP_BOOLEAN_OPTIONAL para cada membro da estrutura que especifica como cada membro deve ser atualizado.
RwVersion
A versão das informações de leitura/gravação a serem definidas. Esse parâmetro deve ser definido como zero para Windows Vista, Windows Server 2008 e Windows 7.
RwSize
O tamanho, em bytes, do buffer apontado pelo parâmetro Rw .
Offset
O deslocamento, em bytes, para o membro na estrutura apontada pelo parâmetro Rw a ser definido. No momento, esse parâmetro não é usado e deve ser definido como zero.
Retornar valor
Se a função for bem-sucedida, o valor retornado será NO_ERROR.
Se a função falhar, o valor retornado será um dos seguintes códigos de erro.
| Código de retorno | Descrição |
|---|---|
|
Acesso negado. Esse erro é retornado sob várias condições que incluem o seguinte: o usuário não tem os privilégios administrativos necessários no computador local ou o aplicativo não está em execução em um shell aprimorado como administrador interno (administrador de RunAs). |
|
O buffer de usuário fornecido não é válido para a operação solicitada. Esse erro será retornado se o parâmetro Row for um ponteiro NULL e o parâmetro RwSize não for zero. |
|
O parâmetro está incorreto. Esse erro será retornado se o parâmetro Row for um ponteiro NULL . |
|
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. |
|
A solicitação não terá suporte. Esse erro será retornado se o RwVersion ou o parâmetro Offset não estiver definido como 0. |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
A função SetPerTcpConnectionEStats é definida no Windows Vista e posterior.
A função SetPerTcpConnectionEStats é usada para habilitar ou desabilitar estatísticas estendidas em uma conexão TCP IPv4 passada no parâmetro Row . Estatísticas estendidas em uma conexão TCP são desabilitadas por padrão. A função SetPerTcpConnectionEStats é usada para definir o valor de um membro nas informações de leitura/gravação para estatísticas estendidas para uma conexão TCP IPv4. O tipo e o formato da estrutura a ser definida são especificados pelo parâmetro EstatsType . O parâmetro Rw contém um ponteiro para a estrutura que está sendo passada. Todos os membros na estrutura apontada pelo parâmetro Rw devem ser especificados.
A única versão das estatísticas de conexão TCP atualmente com suporte é a versão zero. Portanto, o parâmetro RwVersion passado para SetPerTcpConnectionEStats deve ser definido como 0.
A estrutura apontada pelo parâmetro Rw passado por essa função depende do valor de enumeração passado no parâmetro EstatsType . A tabela a seguir indica o tipo de estrutura que deve ser passado no parâmetro Rw para cada tipo de parâmetro EstatsType possível.
| EstatsType | Estrutura apontada por 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 |
O parâmetro Offset não é usado no momento e deve ser definido como 0. As estruturas possíveis apontadas pelo parâmetro Rw têm um único membro, exceto a estrutura TCP_ESTATS_BANDWIDTH_RW_v0 . Quando o parâmetro EstatsType é definido como TcpConnectionEstatsBandwidth, a estrutura TCP_ESTATS_BANDWIDTH_RW_v0 apontada pelo parâmetro Rw deve ter ambos os membros da estrutura definidos como os valores preferenciais em uma única chamada para a função SetPerTcpConnectionEStats .
Se o parâmetro RwSize estiver definido como 0, a função SetPerTcpConnectionEStats retornará NO_ERROR e não fará alterações nas estatísticas estendidas status.
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 SetPerTcpConnectionEStats deve ser uma entrada para uma conexão TCP IPv4 existente.
Depois que estatísticas estendidas são habilitadas em uma conexão TCP para IPv4, os aplicativos chamam a função GetPerTcpConnectionEStats para recuperar estatísticas estendidas na conexão TCP.
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.
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 no Windows Server 2008. 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 no Windows Vista ou no Windows Server 2008 não tiver esse arquivo de manifesto, um usuário conectado como membro do grupo Administradores que não seja o Administrador interno deverá executar o aplicativo em um shell avançado como administrador interno (administrador de RunAs) para que essa função tenha êxito.
Em versões do Windows anteriores ao Windows 10, versão 1709 (Fall Creators Update), você pode usar SetPerTcpConnectionEStats para desabilitar e reabilitar estatísticas em uma conexão, fazendo com que os contadores de estatísticas sejam redefinidos para zero. A partir de Windows 10, versão 1709 (Fall Creators Update), alguns contadores de estatísticas não são redefinidos quando as estatísticas são desabilitadas e reabilitadas. Além disso, se dois aplicativos estiverem monitorando estatísticas para a mesma conexão, um aplicativo poderá confundir o outro desabilitando estatísticas. Por esses motivos, recomendamos que seu aplicativo se abstiver de desabilitar estatísticas em conexões. Para detectar alterações ao longo do tempo, você deve salvar os valores de contador lidos por uma chamada anterior para GetPerTcpConnectionEStats e subtraí-los daqueles lidos por uma chamada subsequente.
Requisitos
| Requisito | Valor |
|---|---|
| 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 |