Função SetIpForwardEntry2 (netioapi.h)
A função SetIpForwardEntry2 define as propriedades de uma entrada de rota IP no computador local.
Sintaxe
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpForwardEntry2(
[in] const MIB_IPFORWARD_ROW2 *Route
);
Parâmetros
[in] Route
Um ponteiro para uma entrada de estrutura MIB_IPFORWARD_ROW2 para uma entrada de rota IP. O membro DestinationPrefix do MIB_IPFORWARD_ROW2 deve ser definido como um prefixo de destino IP válido, o membro NextHop do MIB_IPFORWARD_ROW2 deve ser definido como uma família de endereços IP e endereço IP válidos e o interfaceLuid ou o membro InterfaceIndex do MIB_IPFORWARD_ROW2 deve ser 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). |
|
Um parâmetro inválido foi passado para a função. Esse erro será retornado se um ponteiro NULL for passado no parâmetro Route , o membro DestinationPrefix do MIB_IPFORWARD_ROW2 apontado pelo parâmetro Route não tiver sido especificado, o membro NextHop do MIB_IPFORWARD_ROW2 apontado pelo parâmetro Route não foi especificado ou os membros InterfaceLuid ou InterfaceIndex do MIB_IPFORWARD_ROW2 apontados pela Rota O parâmetro não foi especificado. |
|
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_IPFORWARD_ROW2 apontado pelo parâmetro Route não puder ser encontrado. |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
A função SetIpForwardEntry2 é definida no Windows Vista e posterior.
A função SetIpForwardEntry2 é usada para definir as propriedades de uma entrada de rota IP existente em um computador local.
O membro DestinationPrefix na estrutura MIB_IPFORWARD_ROW2 apontada pelo parâmetro Route deve ser inicializado para um prefixo de endereço IP válido e família. O membro NextHop na estrutura de MIB_IPFORWARD_ROW2 apontada pelo parâmetro Route deve ser inicializado para um endereço IP e uma família válidos. Além disso, pelo menos um dos seguintes membros na estrutura MIB_IPFORWARD_ROW2 apontado para o parâmetro Route deve ser inicializado para a interface: 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 na qual adicionar o endereço IP unicast. 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.
O deslocamento de métrica de rota especificado no membro Métrica da estrutura de MIB_IPFORWARD_ROW2 apontada pelo parâmetro Route representa apenas parte da métrica de rota completa. A métrica completa é uma combinação desse deslocamento de métrica de rota adicionada à métrica de interface especificada no membro Métrica da estrutura MIB_IPINTERFACE_ROW da interface associada. Um aplicativo pode recuperar a métrica de interface chamando a função GetIpInterfaceEntry .
Os membros Age e Origin da estrutura MIB_IPFORWARD_ROW2 apontada pela Linha são ignorados quando a função SetIpForwardEntry2 é chamada. Esses membros são definidos pela pilha de rede e não podem ser alterados usando a função SetIpForwardEntry2 .
A função SetIpForwardEntry2 falhará se os membros DestinationPrefix e NextHop do MIB_IPFORWARD_ROW2 apontados pelo parâmetro Route não corresponderem a uma entrada de rota IP na interface especificada.
A função SetIpForwardEntry2 só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se SetIpForwardEntry2 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 SetIpForwardEntry2 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 |