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 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. Este erro é retornado se um ponteiro de NULL for passado no parâmetro Row, o endereço membro da estrutura de 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 ambos InterfaceLuid e InterfaceIndex membros da estrutura MIB_UNICASTIPADDRESS_ROW não foram especificados. Este erro também é retornado para outros erros nos valores que são definidos para membros na estrutura MIB_UNICASTIPADDRESS_ROW. Esses erros incluem as seguintes situações: O membro do ValidLifetime é menor do que o membro do PreferredLifetime. O membro PrefixOrigin está definido como IpPrefixOriginUnchanged e o SuffixOrigin não está definido como IpSuffixOriginUnchanged. O membro PrefixOrigin não está definido como IpPrefixOriginUnchanged e o SuffixOrigin está definido como IpSuffixOriginUnchanged. O membro PrefixOrigin não está 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 valores possíveis das enumerações NL_PREFIX_ORIGIN e NL_SUFFIX_ORIGIN, consulte MIB_UNICASTIPADDRESS_ROW.
STATUS_NOT_FOUND	A interface especificada não pôde ser encontrada. Este erro é retornado se a função não conseguir encontrar a interface de rede especificada pelo InterfaceLuid ou InterfaceIndex membro da estrutura de MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta.
STATUS_NOT_SUPPORTED	A solicitação não é suportada. Este erro será retornado se nenhuma pilha IPv4 estiver localizada no computador local e um endereço IPv4 tiver sido especificado no Address membro 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. Este erro é retornado se o endereço membro da estrutura de MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro de linha aponta for uma duplicata de um endereço IP unicast existente na interface especificada pelo InterfaceLuid ou InterfaceIndex membro do MIB_UNICASTIPADDRESS_ROW.
Outros	Use a função FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

Use a funçãoInitializeUnicastIpAddressEntry para inicializar os membros de uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW com valores padrão. 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 de MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta.

Endereço
Defina como um endereço IPv4 ou IPv6 unicast válido e 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 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 OnLinkPrefixLength membro 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 OnLinkPrefixLength membro 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, seu driver poderá alterar o endereço IP chamando SetUnicastIpAddressEntry com o membro OnLinkPrefixLength definido para o valor correto.

O DadState, ScopeIde CreationTimeStamp membros da estrutura de MIB_UNICASTIPADDRESS_ROW para os quais 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 do 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 de 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 seu 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 endereço membro da estrutura de MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta não é utilizável imediatamente. O endereço IP é utilizável após o processo de deteção de endereço duplicado ter sido concluído com êxito. Pode levar vários segundos para que o processo de deteção de endereço duplicado seja concluído, porque os pacotes IP devem ser enviados e as respostas potenciais devem ser esperadas. Para IPv6, o processo de deteção de endereço duplicado normalmente leva cerca de 1 segundo. Para IPv4, o processo de deteção de endereços duplicados normalmente leva cerca de 3 segundos.

Depois que um driver chama o função de 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 deteçã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 estiver definido como IpDadStatePreferred, o endereço IP agora é utilizável. Se o valor do membro DadState estiver definido como IpDadStateTentative, a deteçã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 estiver definido como IpDadStateTentative. Se o valor do membro DadState retornar com algum valor diferente de IpDadStatePreferred ou IpDadStateTentative, a deteção de endereço duplicado falhou e o endereço IP não é utilizável.
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çãoNotifyUnicastIpAddressChange para registrar o driver a ser notificado de 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 for recebida para o endereço IP que está sendo criado, chame o função GetUnicastIpAddressEntry para recuperar o membro DadState. Se o valor do membro DadState estiver definido como IpDadStatePreferred, o endereço IP agora é utilizável. Se o valor do membro DadState estiver definido como IpDadStateTentative, a deteçã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 deteção de endereço duplicado falhou e o endereço IP não é utilizável.

Se, durante o processo de deteção de endereço duplicado, a mídia for desconectada e, em seguida, reconectada, o processo de deteçã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 IPv6 ou 3 segundos para IPv4.

Requerimentos

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