Função SetUnicastIpAddressEntry (netioapi.h)

Artigo
03/15/2023

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

Sintaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
  [in] const MIB_UNICASTIPADDRESS_ROW *Row
);

Parâmetros

[in] Row

Um ponteiro para uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW para uma entrada de endereço IP unicast existente.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos códigos de erro a seguir.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	Acesso negado. Esse erro é retornado sob várias condições que incluem o seguinte: o usuário não tem os privilégios administrativos necessários no computador local ou o aplicativo não está em execução em um shell aprimorado como administrador interno (administrador RunAs).
ERROR_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 do MIB_UNICASTIPADDRESS_ROW apontado pelo parâmetro Row não tiver sido definido como um endereço IPv4 ou IPv6 unicast válido ou os membros InterfaceLuid ou InterfaceIndex do MIB_UNICASTIPADDRESS_ROW apontados pelo parâmetro 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 o seguinte: se o membro ValidLifetime for menor que o membro PreferredLifetime , se o membro PrefixOrigin estiver definido como IpPrefixOriginUnchanged e o SuffixOrigin não for definido como IpSuffixOriginUnchanged, se o membro PrefixOrigin não estiver definido como IpPrefixOriginUnchanged e o SuffixOrigin for definido como IpSuffixOriginUnchanged, se o PrefixOrigin member não será definido como um valor da enumeração NL_PREFIX_ORIGIN , se o membro SuffixOrigin não estiver definido como um valor da enumeração NL_SUFFIX_ORIGIN ou se o membro OnLinkPrefixLength for 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).
ERROR_NOT_FOUND	Não foi possível encontrar a interface especificada. Esse erro será retornado se o adaptador de rede especificado pelo membro InterfaceLuid ou InterfaceIndex do MIB_UNICASTIPADDRESS_ROW apontado pelo parâmetro Row não puder ser encontrado.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv4 estiver no computador local e um endereço IPv4 tiver sido especificado no membro AddressMIB_UNICASTIPADDRESS_ROW apontado pelo parâmetro Row ou se nenhuma pilha IPv6 estiver no computador local e um endereço IPv6 tiver sido especificado no membro Address .
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função SetUnicastIpAddressEntry é definida no Windows Vista e posterior.

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

Um aplicativo 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 aplicativo normalmente salvaria o membro InterfaceLuid ou InterfaceIndex antes de chamar InitializeUnicastIpAddressEntry e restauraria um desses membros após a chamada.

O membro Address na estrutura MIB_UNICASTIPADDRESS_ROW apontada pelo parâmetro Row deve ser inicializado para um endereço IPv4 ou IPv6 válido e família. Além disso, pelo menos um dos seguintes membros na estrutura MIB_UNICASTIPADDRESS_ROW apontado para o parâmetro Row deve ser inicializado: InterfaceLuid ou InterfaceIndex.

Os campos são usados na ordem listada acima. Portanto, se InterfaceLuid for especificado, esse membro será usado para determinar a interface. Se nenhum valor tiver sido definido para o membro InterfaceLuid (os valores desse membro foram definidos como zero), o membro InterfaceIndex será usado em seguida para determinar a interface.

Se o membro OnLinkPrefixLength do MIB_UNICASTIPADDRESS_ROW apontado pelo parâmetro Row 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. Portanto, para um endereço IPv4 unicast, OnLinkPrefixLength é definido como 32 e OnLinkPrefixLength é definido como 128 para um endereço IPv6 unicast. Se isso 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 aplicativo deverá definir esse membro com o valor correto antes de chamar SetUnicastIpAddressEntry.

Os membros DadState, ScopeId e CreationTimeStamp da estrutura MIB_UNICASTIPADDRESS_ROW apontada pela Linha são ignorados quando a função SetUnicastIpAddressEntry é chamada. 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.

A função SetUnicastIpAddressEntry só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se SetUnicastIpAddressEntry for chamado por um usuário que não seja membro do grupo Administradores, a chamada de função falhará e ERROR_ACCESS_DENIED será retornado.

A função SetUnicastIpAddressEntry também pode falhar devido ao UAC (controle de conta de usuário) no Windows Vista e posterior. Se um aplicativo que contém essa função for executado por um usuário conectado como um membro do grupo Administradores diferente do Administrador interno, essa chamada falhará, a menos que o aplicativo tenha sido marcado no arquivo de manifesto com um requestedExecutionLevel definido como requireAdministrator. Se o aplicativo não tiver esse arquivo de manifesto, um usuário conectado como membro do grupo Administradores diferente do Administrador interno deverá executar o aplicativo em um shell aprimorado como administrador interno (administrador RunAs) para que essa função tenha êxito.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	netioapi.h (inclua Iphlpapi.h)
Biblioteca	Iphlpapi.lib
DLL	Iphlpapi.dll