Compartilhar via


Função CreateIpForwardEntry2 (netioapi.h)

A função CreateIpForwardEntry2 cria uma nova entrada de rota IP no computador local.

Sintaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API CreateIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Row
);

Parâmetros

[in] Row

Um ponteiro para uma entrada de estrutura MIB_IPFORWARD_ROW2 para uma entrada de rota IP.

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

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 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 Row , o membro DestinationPrefix do MIB_IPFORWARD_ROW2 apontado pelo parâmetro Row não tiver sido especificado, o membro NextHop do MIB_IPFORWARD_ROW2 apontado pelo parâmetro Row não tiver sido especificado ou os membros InterfaceLuid ou InterfaceIndex do MIB_IPFORWARD_ROW2 apontados pela linha O parâmetro não foi especificado. Esse erro também será retornado se o membro PreferredLifetime especificado no MIB_IPFORWARD_ROW2 for maior que o membro ValidLifetime ou se o SitePrefixLength no MIB_IPFORWARD_ROW2 for maior que o comprimento do prefixo especificado no DestinationPrefix.
ERROR_NOT_FOUND
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_IPNET_ROW2 apontado pelo parâmetro Row não puder ser encontrado.
ERROR_NOT_SUPPORTED
A solicitação não terá suporte. Esse erro será retornado se a interface especificada não der suporte a rotas. Esse erro também será retornado se nenhuma pilha IPv4 estiver no computador local e AF_INET tiver sido especificado na família de endereços no membro DestinationPrefix do MIB_IPFORWARD_ROW2 apontado pelo parâmetro Row . Esse erro também será retornado se nenhuma pilha IPv6 estiver no computador local e AF_INET6 tiver sido especificado para a família de endereços no membro DestinationPrefix .
ERROR_OBJECT_ALREADY_EXISTS
O objeto já existe. Esse erro será retornado se o membro DestinationPrefix do MIB_IPFORWARD_ROW2 apontado pelo parâmetro Row for uma duplicata de uma entrada de rota IP existente na interface especificada pelo membro InterfaceLuid ou InterfaceIndex do MIB_IPFORWARD_ROW2.
Outros
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

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

A função CreateIpForwardEntry2 é usada para adicionar uma nova entrada de endereço IP vizinho em um computador local. A função InitializeIpForwardEntry deve ser usada para inicializar os membros de uma entrada de estrutura MIB_IPFORWARD_ROW2 com valores padrão. Em seguida, um aplicativo pode alterar os membros na entrada MIB_IPFORWARD_ROW2 que deseja modificar e, em seguida, chamar a função CreateIpForwardEntry2 .

O membro DestinationPrefix na estrutura MIB_IPFORWARD_ROW2 apontada pelo parâmetro Row deve ser inicializado para um prefixo de endereço IPv4 ou IPv6 válido. O membro NextHop na estrutura MIB_IPFORWARD_ROW2 apontada pelo parâmetro Row deve ser inicializado para um endereço IPv4 ou IPv6 válido e família. Além disso, pelo menos um dos seguintes membros na estrutura MIB_IPFORWARD_ROW2 apontado para o parâmetro Row deve ser inicializado para a interface: InterfaceLuid ou InterfaceIndex.

Os campos são usados na ordem listada acima. Portanto, se InterfaceLuid for especificado, esse membro será usado para determinar a interface na qual adicionar a entrada de rota IP. 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 MIB_IPFORWARD_ROW2 apontada pelo parâmetro Row representa apenas parte da métrica de rota completa. A métrica completa é uma combinação desse deslocamento de métrica de rota adicionado à 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 CreateIpForwardEntry2 é chamada. Esses membros são definidos pela pilha de rede e não podem ser definidos usando a função CreateIpForwardEntry2 .

A função CreateIpForwardEntry2 falhará se os membros DestinationPrefix e NextHop do MIB_IPFORWARD_ROW2 apontados pelo parâmetro Row forem uma duplicata de uma entrada de rota IP existente na interface especificada nos membros InterfaceLuid ou InterfaceIndex .

A função CreateIpForwardEntry2 só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se CreateIpForwardEntry2 for chamado por um usuário que não seja 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 um 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 como requireAdministrator. 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

Confira também

DeleteIpForwardEntry2

GetBestRoute2

GetIpForwardEntry2

GetIpForwardTable2

GetIpInterfaceEntry

InitializeIpForwardEntry

MIB_IPFORWARD_ROW2

MIB_IPFORWARD_TABLE2

MIB_IPINTERFACE_ROW

NotifyRouteChange2

SetIpForwardEntry2