Função SetIpStatisticsEx (iphlpapi.h)

Artigo
08/24/2023

A função SetIpStatisticsEx ativa ou desativa o encaminhamento de IP e define o valor de TTL (vida útil) padrão para o computador local.

Sintaxe

IPHLPAPI_DLL_LINKAGE ULONG SetIpStatisticsEx(
  [in] PMIB_IPSTATS Statistics,
       ULONG        Family
);

Parâmetros

[in] Statistics

Um ponteiro para uma estrutura MIB_IPSTATS . O chamador deve definir os membros dwForwarding e dwDefaultTTL dessa estrutura como os novos valores. Para manter um dos membros no valor atual, use MIB_USE_CURRENT_TTL ou MIB_USE_CURRENT_FORWARDING.

Family

A família de endereços para a qual o encaminhamento e o TTL devem ser definidos.

Os valores possíveis para a família de endereços são listados no arquivo de cabeçalho Winsock2.h . Observe que os valores para a família de endereços AF_ e as constantes da família de protocolos PF_ são idênticos (por exemplo, AF_INET e PF_INET), para que qualquer constante possa ser usada.

No SDK do Windows lançado para Windows Vista e posterior, a organização dos arquivos de cabeçalho foi alterada e os valores possíveis para esse membro são definidos no arquivo de cabeçalho Ws2def.h . Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente em Winsock2.h e nunca deve ser usado diretamente.

Os valores com suporte no momento são AF_INET e AF_INET6.

Valor	Significado
AF_INET 2	A família de endereços IPv4 (Protocolo de Internet versão 4). Quando esse parâmetro é especificado, essa função define as opções de encaminhamento e TTL para entradas IPv4.
AF_INET6 23	A família de endereços IPv6 (Internet Protocol versão 6). Quando esse parâmetro é especificado, essa função define as opções de encaminhamento e TTL para entradas IPv6.

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 seguintes códigos de erro.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O acesso foi 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	Um parâmetro inválido foi passado para a função. Esse erro será retornado se um ponteiro NULL for passado no parâmetro pIpStats ou o parâmetro Family não estiver definido como AF_INET e AF_INET6. Esse erro também será retornado se o membro dwForwarding na estrutura MIB_IPSTATS apontada pelo parâmetro pIpStats contiver um valor diferente de MIB_IP_NOT_FORWARDING, MIB_IP_FORWARDING ou MIB_USE_CURRENT_FORWARDING.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv4 estiver no computador local e AF_INET tiver sido especificado no parâmetro Family ou nenhuma pilha IPv6 estiver no computador local e AF_INET6 tiver sido especificado no membro da Família .
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

Para definir apenas o TTL padrão, o chamador também pode usar a função SetIpTTL .

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

A função SetIpStatisticsEx 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 no 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.

Requisitos


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