Função CreateIpForwardEntry2

Artigo
03/08/2023

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

Sintaxe

NETIOAPI_API CreateIpForwardEntry2(
  _In_ const MIB_IPFORWARD_ROW2 *Row
);

Parâmetros

Linha [in]
Um ponteiro para uma entrada de estrutura MIB_IPFORWARD_ROW2 para uma entrada de rota IP.

Retornar valor

CreateIpForwardEntry2 retornará STATUS_SUCCESS se a função for bem-sucedida.

Se a função falhar, CreateIpForwardEntry2 retornará um dos seguintes códigos de erro:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se ocorrer uma das seguintes situações: Um ponteiro NULL é passado no parâmetro Row . O membro DestinationPrefix da estrutura MIB_IPFORWARD_ROW2 para a qual o parâmetro Row aponta não foi especificado. O membro NextHop da estrutura MIB_IPFORWARD_ROW2 não foi especificado. Os membros InterfaceLuid e InterfaceIndex da estrutura MIB_IPFORWARD_ROW2 não foram especificados. O membro PreferredLifetime da estrutura MIB_IPFORWARD_ROW2 é maior que o membro ValidLifetime . O membro SitePrefixLength da estrutura MIB_IPFORWARD_ROW2 é maior que o comprimento do prefixo especificado pelo membro DestinationPrefix . Esse erro será retornado se um ponteiro NULL for passado no parâmetro Row , o membro DestinationPrefix da estrutura MIB_IPFORWARD_ROW2 apontada pelo parâmetro Row não tiver sido especificado, o membro NextHop da estrutura MIB_IPFORWARD_ROW2 não foi especificado ou os membros InterfaceLuid e InterfaceIndex da estrutura MIB_IPFORWARD_ROW2 não foram especificados. Esse erro também será retornado se o membro PreferredLifetime especificado na estrutura MIB_IPFORWARD_ROW2 for maior que o membro ValidLifetime ou se o SitePrefixLength na estrutura MIB_IPFORWARD_ROW2 for maior que o tamanho do prefixo especificado no membro DestinationPrefix .
STATUS_NOT_FOUND	Não foi possível encontrar a interface especificada. Esse erro será retornado se a função não puder encontrar o adaptador de rede especificado pelo membro InterfaceLuid ou InterfaceIndex da estrutura MIB_IPNET_ROW2 para a qual o parâmetro Row aponta.
STATUS_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se a interface especificada não oferecer suporte a rotas. Esse erro será retornado se nenhuma pilha IPv4 estiver localizada no computador local e AF_INET tiver sido especificado na família de endereços no membro DestinationPrefix da estrutura MIB_IPFORWARD_ROW2 para a qual o parâmetro Row aponta ou se nenhuma pilha IPv6 estiver localizada no computador local e AF_INET6 tiver sido especificada 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 da estrutura MIB_IPFORWARD_ROW2 para a qual o parâmetro Row aponta for uma duplicata de uma entrada de rota IP existente na interface especificada pelo membro InterfaceLuid ou InterfaceIndex da estrutura MIB_IPFORWARD_ROW2.
Outros	Use a função FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

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

O driver deve inicializar os seguintes membros da estrutura MIB_IPFORWARD_ROW2 para a qual o parâmetro Row aponta:

Defina DestinationPrefix como um prefixo de endereço IPv4 ou IPv6 válido.
Defina NextHop como um endereço IPv4 ou IPv6 válido e uma família.
Defina InterfaceLuid ou InterfaceIndex como o LUID ou o valor de índice da interface.

Os membros InterfaceLuid e InterfaceIndex são usados na ordem listada anteriormente. Portanto, se a InterfaceLuid for especificada, 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 (o valor desse membro foi definido 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 para a qual o parâmetro Row aponta 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 driver pode recuperar a métrica de interface chamando a função GetIpInterfaceEntry .

Os membros Age e Origin da estrutura MIB_IPFORWARD_ROW2 para a qual o parâmetro Row aponta 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 da estrutura MIB_IPFORWARD_ROW2 para a qual o parâmetro Row aponta sejam uma duplicata de uma entrada de rota IP existente na interface especificada nos membros InterfaceLuid ou InterfaceIndex .

Requisitos

Plataforma de destino	Universal
Versão	Disponível no Windows Vista e versões posteriores dos sistemas operacionais Windows.
parâmetro	Netioapi.h (inclua Netioapi.h)
Biblioteca	Netio.lib
IRQL	< DISPATCH_LEVEL