Função SetIpInterfaceEntry (netioapi.h)
A função SetIpInterfaceEntry define as propriedades de uma interface IP no computador local.
Sintaxe
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpInterfaceEntry(
[in, out] PMIB_IPINTERFACE_ROW Row
);
Parâmetros
[in, out] Row
Um ponteiro para uma entrada de estrutura MIB_IPINTERFACE_ROW para uma interface. Na entrada, o membro da família do MIB_IPINTERFACE_ROW deve ser definido como AF_INET6 ou AF_INET e o InterfaceLuid ou o membro InterfaceIndex do MIB_IPINTERFACE_ROW devem ser especificados. Em um retorno bem-sucedido, o membro InterfaceLuid do MIB_IPINTERFACE_ROW será preenchido se InterfaceIndex membro da entrada MIB_IPINTERFACE_ROW tiver sido especificado.
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 sistema não pode encontrar o arquivo especificado. Esse erro será retornado se o LUID da interface de rede ou o índice de interface especificado pelo membro InterfaceLuid ou InterfaceIndex do MIB_IPINTERFACE_ROW apontado pelo parâmetro Row não for um valor no computador local. |
|
Um parâmetro inválido foi passado para a função. Esse erro será retornado se um ponteiro NULL for passado no parâmetro Row , o membro Family do MIB_IPINTERFACE_ROW apontado pelo parâmetro Row não tiver sido especificado como AF_INET ou AF_INET6 ou os membros InterfaceLuid ou InterfaceIndex do MIB_IPINTERFACE_ROW apontados pelo parâmetro Row não foram especificados. |
|
Não foi possível encontrar a interface especificada. Esse erro será retornado se o adaptador de rede especificado pelo membro InterfaceLuid ou InterfaceIndex do MIB_IPINTERFACE_ROW apontado pelo parâmetro Row não corresponder à família de endereços IP especificada no membro Da família na estrutura MIB_IPINTERFACE_ROW . |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
A função SetIpInterfaceEntry é definida no Windows Vista e posterior.
A função SetIpInterfaceEntry pode ser usada para modificar uma entrada de interface IP existente.
Na entrada, o membro Family na estrutura MIB_IPINTERFACE_ROW apontada pelo parâmetro Row deve ser inicializado para AF_INET ou AF_INET6. Além da entrada, pelo menos um dos seguintes membros na estrutura MIB_IPINTERFACE_ROW apontado para o parâmetro Row deve ser inicializado: InterfaceLuid ou InterfaceIndex.
Os campos são usados na ordem listada acima. Portanto, se o InterfaceLuid for especificado, esse membro será usado para determinar a interface. Se nenhum valor tiver sido definido para o membro InterfaceLuid (os valores desse membro foram definidos como zero), o membro InterfaceIndex será usado em seguida para determinar a interface.
Na saída, o membro InterfaceLuid da estrutura MIB_IPINTERFACE_ROW apontada pelo parâmetro Row será preenchido se InterfaceIndex tiver sido especificado.
Os membros MaxReassemblySize, MinRouterAdvertisementInterval, MaxRouterAdvertisementInterval , Connected, SupportsWakeUpPatterns, SupportsNeighborDiscovery, SupportsRouterDiscovery, ReachableTime, TransmitOffload e ReceiveOffload da estrutura MIB_IPINTERFACE_ROW apontada pela Linha são ignorados quando a função SetIpInterfaceEntry é chamada. Esses membros são definidos pela pilha de rede e não podem ser alterados usando a função SetIpInterfaceEntry .
Um aplicativo normalmente chamaria a função GetIpInterfaceTable para recuperar as entradas da interface IP no computador local ou chamar a função GetIpInterfaceEntry para recuperar apenas a entrada da interface IP a ser modificada. A estrutura MIB_IPINTERFACE_ROW para a entrada de interface IP específica pode então ser modificada e um ponteiro para essa estrutura passado para a função SetIpInterfaceEntry no parâmetro Row . No entanto, para IPv4, um aplicativo não deve tentar modificar o membro SitePrefixLength da estrutura MIB_IPINTERFACE_ROW . Para IPv4, o membro SitePrefixLength deve ser definido como 0.
Outro método possível para modificar uma entrada de interface IP existente é usar a função InitializeIpInterfaceEntry para inicializar os campos de uma entrada de estrutura MIB_IPINTERFACE_ROW com valores padrão. Em seguida, defina o membro Family e os membros InterfaceIndex ou InterfaceLuid na estrutura MIB_IPINTERFACE_ROW apontada pelo parâmetro Row para corresponder à interface IP para alterar. Em seguida, um aplicativo pode alterar os campos na entrada MIB_IPINTERFACE_ROW que deseja modificar e, em seguida, chamar a função SetIpInterfaceEntry . No entanto, para IPv4, um aplicativo não deve tentar modificar o membro SitePrefixLength da estrutura MIB_IPINTERFACE_ROW . Para IPv4, o membro SitePrefixLength deve ser definido como 0. Cuidado deve ser usado com essa abordagem porque a única maneira de determinar todos os campos que estão sendo alterados seria comparar os campos no MIB_IPINTERFACE_ROW da entrada de interface IP específica com campos definidos pela função InitializeIpInterfaceEntry quando um MIB_IPINTERFACE_ROW é inicializado para valores padrão.
O acesso simultâneo não privilegiado a várias redes de diferentes requisitos de segurança cria uma falha de segurança e permite que um aplicativo sem privilégios retransmitisse dados acidentalmente entre as duas redes. Um exemplo típico é o acesso simultâneo a uma VPN (rede virtual privada) e à Internet. O Windows Server 2003 e o Windows XP usam um modelo de host fraco, em que o RAS impede esse acesso simultâneo aumentando a métrica de rota de todas as rotas padrão em relação a outras interfaces. Assim, todo o tráfego é roteado por meio da interface VPN, interrompendo outras conectividades de rede.
No Windows Vista e posterior, um modelo de host forte é usado por padrão. Se um endereço IP de origem for especificado na pesquisa de rota usando GetBestRoute2 ou GetBestRoute, a pesquisa de rota será restrita à interface do endereço IP de origem. A modificação da métrica de rota por RAS não tem efeito, pois a lista de rotas potenciais nem sequer tem a rota para a interface VPN, permitindo assim o tráfego para a Internet. O membro DisableDefaultRoutes do MIB_IPINTERFACE_ROW pode ser usado para desabilitar usando a rota padrão em uma interface. Esse membro pode ser usado como uma medida de segurança por clientes VPN para restringir o túnel dividido quando o túnel dividido não é exigido pelo cliente VPN. Um cliente VPN pode chamar a função SetIpInterfaceEntry para definir o membro DisableDefaultRoutes como TRUE quando necessário. Um cliente VPN pode consultar o estado atual do membro DisableDefaultRoutes chamando a função GetIpInterfaceEntry .
O
A função SetIpInterfaceEntry só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se SetIpInterfaceEntry 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.
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 | netioapi.h (inclua Iphlpapi.h) |
| Biblioteca | Iphlpapi.lib |
| DLL | Iphlpapi.dll |