Função SetPerTcp6ConnectionEStats (iphlpapi.h)

Artigo
08/24/2023

A função SetPerTcp6ConnectionEStats define um valor nas informações de leitura/gravação de uma conexão TCP IPv6. Essa função é usada para habilitar ou desabilitar estatísticas estendidas para uma conexão TCP IPv6.

Sintaxe

IPHLPAPI_DLL_LINKAGE ULONG SetPerTcp6ConnectionEStats(
  PMIB_TCP6ROW    Row,
  TCP_ESTATS_TYPE EstatsType,
  PUCHAR          Rw,
  ULONG           RwVersion,
  ULONG           RwSize,
  ULONG           Offset
);

Parâmetros

Row

Um ponteiro para uma estrutura MIB_TCP6ROW para uma conexão TCP IPv6.

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 .

Valor	Significado
TcpConnectionEstatsData	Esse valor especifica informações de transferência de dados estendidas para uma conexão TCP. Quando esse valor é especificado, o buffer apontado pelo parâmetro Rw deve apontar para uma estrutura TCP_ESTATS_DATA_RW_v0 .
TcpConnectionEstatsSndCong	Esse valor especifica o congestionamento do remetente para uma conexão TCP. Quando esse valor é especificado, o buffer apontado pelo parâmetro Rw deve apontar para uma estrutura de TCP_ESTATS_SND_CONG_RW_v0 .
TcpConnectionEstatsPath	Esse valor especifica informações de medição de caminho estendido para uma conexão TCP. Quando esse valor é especificado, o buffer apontado pelo parâmetro Rw deve apontar para uma estrutura de TCP_ESTATS_PATH_RW_v0 .
TcpConnectionEstatsSendBuff	Esse valor especifica informações de enfileiramento de saída estendidas para uma conexão TCP. Quando esse valor é especificado, o buffer apontado pelo parâmetro Rw deve apontar para uma estrutura TCP_ESTATS_SEND_BUFF_RW_v0 .
TcpConnectionEstatsRec	Esse valor especifica informações estendidas do receptor local para uma conexão TCP. Quando esse valor é especificado, o buffer apontado pelo parâmetro Rw deve apontar para uma estrutura de TCP_ESTATS_REC_RW_v0 .
TcpConnectionEstatsObsRec	Esse valor especifica informações estendidas do receptor remoto para uma conexão TCP. Quando esse valor é especificado, o buffer apontado pelo parâmetro Rw deve apontar para uma estrutura TCP_ESTATS_OBS_REC_RW_v0 .
TcpConnectionEstatsBandwidth	Esse valor especifica estatísticas de estimativa de largura de banda para uma conexão TCP na largura de banda. Quando esse valor é especificado, o buffer apontado pelo parâmetro Rw deve apontar para uma estrutura TCP_ESTATS_BANDWIDTH_RW_v0 .
TcpConnectionEstatsFineRtt	Esse valor especifica estatísticas de estimativa de RTT (tempo de ida e volta) refinadas para uma conexão TCP. Quando esse valor é especificado, o buffer apontado pelo parâmetro Rw deve apontar para uma estrutura TCP_ESTATS_FINE_RTT_RW_v0 .

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
ERROR_ACCESS_DENIED	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).
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 o parâmetro Row for um ponteiro NULL e o parâmetro RwSize não for zero.
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 RwVersion ou o parâmetro Offset não estiver definido como 0.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

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

A função SetPerTcp6ConnectionEStats é usada para habilitar ou desabilitar estatísticas estendidas para a conexão TCP IPv6 passada no parâmetro Row . Estatísticas estendidas em uma conexão TCP são desabilitadas por padrão.

A função SetPerTcp6ConnectionEStats é usada para definir o valor de um membro nas informações de leitura/gravação para estatísticas estendidas para uma conexão TCP IPv6. 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. O membro a ser definido nessa estrutura é especificado pelo parâmetro Offset . 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 SetPerTcp6ConnectionEStats 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. 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 SetPerTcp6ConnectionEStats .

Se o parâmetro RwSize estiver definido como 0, a função SetPerTcp6ConnectionEStats retornará NO_ERROR e não fará alterações nas estatísticas estendidas status.

A função GetTcp6Table é usada para recuperar a tabela de conexões TCP IPv6 no computador local. Essa função retorna uma estrutura MIB_TCP6TABLE que contém uma matriz de entradas MIB_TCP6ROW . O parâmetro Row passado para a função SetPerTcp6ConnectionEStats deve ser uma entrada para uma conexão TCP IPv6 existente.

Depois que estatísticas estendidas são habilitadas em uma conexão TCP para IPv6, um aplicativo chama a função GetPerTcp6ConnectionEStats para recuperar estatísticas estendidas na conexão TCP.

A função GetPerTcp6ConnectionEStats 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 IPv4, consulte as funções GetPerTcpConnectionEStats e SetPerTcpConnectionEStats .

A função SetPerTcp6ConnectionEStats só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se SetPerTcp6ConnectionEStats 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.

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