Função SetUnicastIpAddressEntry

Artigo
03/08/2023

A função SetUnicastIpAddressEntry define as propriedades de uma entrada de endereço IP unicast existente em um computador local.

Sintaxe

NETIOAPI_API SetUnicastIpAddressEntry(
  _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 existente.

Retornar valor

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

Se a função falhar, SetUnicastIpAddressEntry 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 os membros InterfaceLuid e InterfaceIndex da estrutura MIB_UNICASTIPADDRESS_ROW não foram especificados.
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_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 Address 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 .
Outros	Use a função FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função GetUnicastIpAddressEntry normalmente é usada para recuperar uma entrada de estrutura de MIB_UNICASTIPADDRESS_ROW existente a ser modificada. Em seguida, um driver pode alterar os membros na entrada MIB_UNICASTIPADDRESS_ROW que deseja modificar e, em seguida, chamar a função SetUnicastIpAddressEntry .

Um driver pode chamar a função InitializeUnicastIpAddressEntry para inicializar os membros de uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW com valores padrão antes de fazer alterações. No entanto, o driver normalmente salva o membro InterfaceLuid ou InterfaceIndex antes de chamar InitializeUnicastIpAddressEntry e restaura um desses membros após a chamada.

O driver deve inicializar os membros a seguir da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta.

Endereço
Defina como um endereço IPv4 ou IPv6 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. 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 membro OnLinkPrefixLength da estrutura MIB_UNICASTIPADDRESS_ROW à qual o parâmetro Row aponta for definido como 255, SetUnicastIpAddressEntry definirá as propriedades de endereço IP unicast para que o membro OnLinkPrefixLength seja igual ao comprimento do endereço IP. Para um endereço IPv4 unicast, OnLinkPrefixLength é definido como 32. Para um endereço IPv6 unicast, OnLinkPrefixLength é definido como 128. Se essas configurações resultarem 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 esse membro como o valor correto antes de chamar SetUnicastIpAddressEntry.

SetUnicastIpAddressEntry ignora os membros DadState, ScopeId e CreationTimeStamp da estrutura MIB_UNICASTIPADDRESS_ROW para a qual o parâmetro Row aponta. Esses membros são definidos pela pilha de rede e não podem ser alterados usando a função SetUnicastIpAddressEntry . O membro ScopeId é determinado automaticamente pela interface na qual o endereço foi adicionado.

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