Função CreateUnicastIpAddressEntry

Artigo
05/03/2024

A função CreateUnicastIpAddressEntry adiciona uma nova entrada de endereço IP unicast no computador local.

Sintaxe

NETIOAPI_API CreateUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

Parâmetros

Linha [em]
Um ponteiro para uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW para uma entrada de endereço IP unicast.

Valor retornado

CreateUnicastIpAddressEntry retorna STATUS_SUCCESS se a função for bem-sucedida.

Se a função falhar, CreateUnicastIpAddressEntry 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 um ponteiro NULL for passado no parâmetro Row, o membro Address da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta não foi definido como um endereço IPv4 ou IPv6 unicast válido ou se os membros InterfaceLuid e InterfaceIndex da estrutura MIB_UNICASTIPADDRESS_ROW não foram especificados. Esse erro também é retornado para outros erros nos valores definidos para membros na estrutura MIB_UNICASTIPADDRESS_ROW. Esses erros incluem as seguintes situações: O membro ValidLifetime é menor que o membro PreferredLifetime . O membro PrefixOrigin é definido como IpPrefixOriginUnchanged e o SuffixOrigin não é definido como IpSuffixOriginUnchanged. O membro PrefixOrigin não está definido como IpPrefixOriginUnchanged e o SuffixOrigin é definido como IpSuffixOriginUnchanged. O membro PrefixOrigin não é definido como um valor da enumeração NL_PREFIX_ORIGIN . O membro SuffixOrigin não é definido como um valor da enumeração NL_SUFFIX_ORIGIN. O membro OnLinkPrefixLength é definido como um valor maior que o comprimento do endereço IP, em bits (32 para um endereço IPv4 unicast ou 128 para um endereço IPv6 unicast). Para obter valores possíveis das enumerações NL_PREFIX_ORIGIN e NL_SUFFIX_ORIGIN, consulte MIB_UNICASTIPADDRESS_ROW.
STATUS_NOT_FOUND	Não foi possível encontrar a interface especificado. Esse erro será retornado se a função não puder localizar a interface de rede especificada pelo membro InterfaceLuid ou InterfaceIndex da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta.
STATUS_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv4 estiver localizada no computador local e um endereço IPv4 tiver sido especificado no membro Endereço da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta, ou se nenhuma pilha IPv6 estiver localizada no computador local e um endereço IPv6 tiver sido especificado no membro Address.
ERROR_OBJECT_ALREADY_EXISTS	O objeto já existe. Esse erro será retornado se o membro Address da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta for uma duplicata de um endereço IP unicast existente na interface especificada pelo membro InterfaceLuid ou InterfaceIndex do MIB_UNICASTIPADDRESS_ROW.
Outras	Use a função FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

Use a função InitializeUnicastIpAddressEntry para inicializar os membros de uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW com valores padrão. Um driver pode alterar os membros na entrada de MIB_UNICASTIPADDRESS_ROW que deseja modificar e, em seguida, chamar a função CreateUnicastIpAddressEntry .

Na entrada, o driver deve inicializar os seguintes membros da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta.

Endereço
Defina como um endereço e uma família IPv4 ou IPv6 unicast válidos.
InterfaceLuid ou InterfaceIndex
Esses membros são usados na ordem listada anteriormente. Portanto, se InterfaceLuid for especificado, esse membro será usado para determinar a interface à qual adicionar o endereço IP unicast. Se nenhum valor foi definido para o membro InterfaceLuid (o valor desse membro foi definido como zero), o membro InterfaceIndex será usado em seguida para determinar a interface.

Se o membro OnLinkPrefixLength da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta estiver definido como 255, CreateUnicastIpAddressEntry adicionará o novo endereço IP unicast com o membro OnLinkPrefixLength definido igual ao comprimento do endereço IP. Portanto, para um endereço IPv4 unicast, o OnLinkPrefixLength é definido como 32 e o OnLinkPrefixLength é definido como 128 para um endereço IPv6 unicast. Se essa configuração resultar na máscara de sub-rede incorreta para um endereço IPv4 ou no prefixo de link incorreto para um endereço IPv6, o driver deverá definir o membro OnLinkPrefixLength com o valor correto antes de chamar CreateUnicastIpAddressEntry.

Se um endereço IP unicast for criado com o membro OnLinkPrefixLength definido incorretamente, o driver poderá alterar o endereço IP chamando SetUnicastIpAddressEntry com o membro OnLinkPrefixLength definido com o valor correto.

Os membros DadState, ScopeId e CreationTimeStamp da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta são ignorados quando a função CreateUnicastIpAddressEntry é chamada. Esses membros são definidos pela pilha de rede. O membro ScopeId é determinado automaticamente pela interface à qual o endereço é adicionado.

A função CreateUnicastIpAddressEntry falhará se o endereço IP unicast que é passado no membro Address da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta for uma duplicata de um endereço IP unicast existente na interface. Observe que o driver pode adicionar um endereço IP de loopback a uma interface de loopback somente usando a função CreateUnicastIpAddressEntry .

O endereço IP unicast que é passado no membro Address da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta não é utilizável imediatamente. O endereço IP pode ser usado após a conclusão bem-sucedida do processo de detecção de endereço duplicado. Pode levar vários segundos para que o processo de detecção de endereço duplicado seja concluído, pois os pacotes IP devem ser enviados e as respostas potenciais devem ser aguardadas. Para IPv6, o processo de detecção de endereços duplicados normalmente leva cerca de 1 segundo. Para IPv4, o processo de detecção de endereços duplicados normalmente leva cerca de 3 segundos.

Depois que um driver chama a função CreateUnicastIpAddressEntry , ele pode usar os seguintes métodos para determinar se um endereço IP ainda é utilizável:

Usar sondagem e a função GetUnicastIpAddressEntry
Depois que a chamada para a função CreateUnicastIpAddressEntry retornar com êxito, pause por 1 a 3 segundos (dependendo se um endereço IPv6 ou IPv4 está sendo criado) para dar tempo para a conclusão bem-sucedida do processo de detecção de endereço de duplicação. Em seguida, chame GetUnicastIpAddressEntry para recuperar a estrutura de MIB_UNICASTIPADDRESS_ROW atualizada e examinar o valor do membro DadState . Se o valor do membro DadState for definido como IpDadStatePreferred, o endereço IP agora poderá ser usado. Se o valor do membro DadState estiver definido como IpDadStateTentative, a detecção de endereço duplicado ainda não foi concluída. Nesse caso, chame a função GetUnicastIpAddressEntry novamente a cada 0,5 segundos enquanto o membro DadState ainda está definido como IpDadStateTentative. Se o valor do membro DadState retornar com algum valor diferente de IpDadStatePreferred ou IpDadStateTentative, a detecção de endereço duplicado falhou e o endereço IP não poderá ser usado.
Chame uma das funções de notificação IP Helper NotifyXxx para configurar uma notificação assíncrona para quando um endereço for alterado
Depois que a chamada para a função CreateUnicastIpAddressEntry retornar com êxito, chame a função NotifyUnicastIpAddressChange para registrar o driver a ser notificado sobre alterações nos endereços IP unicast IPv6 ou IPv4, dependendo do tipo de endereço IP que está sendo criado. Quando uma notificação é recebida para o endereço IP que está sendo criado, chame a função GetUnicastIpAddressEntry para recuperar o membro DadState . Se o valor do membro DadState for definido como IpDadStatePreferred, o endereço IP agora poderá ser usado. Se o valor do membro DadState estiver definido como IpDadStateTentative, a detecção de endereço duplicado ainda não foi concluída e o driver deverá aguardar notificações futuras. Se o valor do membro DadState retornar com algum valor diferente de IpDadStatePreferred ou IpDadStateTentative, a detecção de endereço duplicado falhou e o endereço IP não poderá ser usado.

Se, durante o processo de detecção de endereço duplicado, a mídia for desconectada e, em seguida, reconectada, o processo de detecção de endereço duplicado será reiniciado. Assim, o tempo para concluir o processo pode aumentar além do valor típico de 1 segundo para IPv6 ou 3 segundos para IPv4.

Requisitos

Plataforma de destino	Universal
Versão	Disponível no Windows Vista e em versões posteriores dos sistemas operacionais Windows.
Cabeçalho	Netioapi.h (incluir Netioapi.h)
Biblioteca	Netio.lib
IRQL	< DISPATCH_LEVEL