Função CreateUnicastIpAddressEntry

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 [in]
  Um ponteiro para uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW para uma entrada de endereço IP unicast.

Valor de retorno

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

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

Observações

Use a função InitializeUnicastIpAddressEntry para inicializar os membros de uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW com valores padrão. Em seguida, um driver pode alterar os membros na entrada 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 à qual o parâmetro Row aponta.

• endereço
  Defina como um endereço IPv4 ou IPv6 unicast válido e uma família.

• 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 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.

Se o OnLinkPrefixLength membro da estrutura MIB_UNICASTIPADDRESS_ROW à qual o parâmetro Linha aponta for 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 está 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 o 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 como o valor correto.

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

A função CreateUnicastIpAddressEntry falhará se o endereço IP unicast que é passado no endereço membro da estrutura MIB_UNICASTIPADDRESS_ROW à qual o parâmetro linha aponta é 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 apenas usando a função CreateUnicastIpAddressEntry.

O endereço IP unicast que é passado no Address membro da estrutura MIB_UNICASTIPADDRESS_ROW à qual o parâmetro Row aponta não é utilizável imediatamente. O endereço IP é utilizável depois que o processo de detecção de endereço duplicado for concluído com êxito. Pode levar vários segundos para que o processo de detecção de endereço duplicado seja concluído porque os pacotes IP devem ser enviados e as respostas potenciais devem ser aguardadas. Para IPv6, o processo de detecção de endereço duplicado normalmente leva cerca de 1 segundo. Para iPv4, o processo de detecção de endereço duplicado 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
  Após a chamada para a função CreateUnicastIpAddressEntry retorna com êxito, pause por 1 a 3 segundos (dependendo se um endereço IPv6 ou IPv4 está sendo criado) para permitir 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 utilizável. Se o valor do membro DadState estiver definido como IpDadStateTentative, a detecção de endereço duplicada 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 falhará e o endereço IP não será utilizável.

• chame uma das funções de notificação NotifyXxx do Auxiliar de IP 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çãoNotifyUnicastIpAddressChange para registrar o driver para ser notificado sobre alterações em endereços IP unicast IPv6 ou IPv4, dependendo do tipo de endereço IP que está sendo criado. Quando uma notificação for 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 utilizável. Se o valor do membro DadState estiver definido como IpDadStateTentative, a detecção de endereço duplicada ainda não foi concluída e o driver deverá aguardar as 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 falhará e o endereço IP não será utilizável.

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

Requisitos

Consulte também

DeleteUnicastIpAddressEntry

GetUnicastIpAddressEntry

GetUnicastIpAddressTable

InitializeUnicastIpAddressEntry

MIB_UNICASTIPADDRESS_ROW

MIB_UNICASTIPADDRESS_TABLE

NL_PREFIX_ORIGIN

NL_SUFFIX_ORIGIN

NotifyIpInterfaceChange

notifyRouteChange2

NotifyStableUnicastIpAddressTable

NotifyTeredoPortChange

NotifyUnicastIpAddressChange

SetUnicastIpAddressEntry