Función SetUnicastIpAddressEntry (netioapi.h)

Artículo
03/13/2024

La función SetUnicastIpAddressEntry establece las propiedades de una entrada de dirección IP de unidifusión existente en el equipo local.

Sintaxis

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

Parámetros

[in] Row

Puntero a una entrada de estructura MIB_UNICASTIPADDRESS_ROW para una entrada de dirección IP de unidifusión existente.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es NO_ERROR.

Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	Acceso denegado. Este error se devuelve en varias condiciones que incluyen lo siguiente: el usuario carece de los privilegios administrativos necesarios en el equipo local o la aplicación no se ejecuta en un shell mejorado como administrador integrado (administrador de RunAs).
ERROR_INVALID_PARAMETER	Se pasó un parámetro no válido a la función. Este error se devuelve si se pasa un puntero NULL en el parámetro Row , el miembro Address del MIB_UNICASTIPADDRESS_ROW al que apunta el parámetro Row no se estableció en una dirección IPv4 o IPv6 de unidifusión válida, o los miembros InterfaceLuid o InterfaceIndex del MIB_UNICASTIPADDRESS_ROW señalados por el parámetro Row no se especificaron. Este error también se devuelve para otros errores en los valores establecidos para los miembros de la estructura MIB_UNICASTIPADDRESS_ROW . Estos errores incluyen lo siguiente: si el miembro ValidLifetime es menor que el miembro PreferredLifetime , si el miembro PrefixOrigin está establecido en IpPrefixOriginUnchanged y el SuffixOrigin Es el no establecido en IpSuffixOriginUnchanged, si el miembro PrefixOriginOrigin no está establecido en IpPrefixOriginUnchanged y El SuffixOrigin Se establece en IpSuffixOriginUnchanged, si el prefijoOriginUnchanged member no se establece en un valor de la enumeración NL_PREFIX_ORIGIN , si el miembro SuffixOrigin no está establecido en un valor de la enumeración NL_SUFFIX_ORIGIN , o si el miembro OnLinkPrefixLength está establecido en un valor mayor que la longitud de la dirección IP, en bits (32 para una dirección IPv4 de unidifusión o 128 para una dirección IPv6 de unidifusión).
ERROR_NOT_FOUND	No se encontró la interfaz especificada. Este error se devuelve si no se encontró la interfaz de red especificada por el miembro InterfaceLuid o InterfaceIndex del MIB_UNICASTIPADDRESS_ROW al que apunta el parámetro Row .
ERROR_NOT_SUPPORTED	No se admite la solicitud. Este error se devuelve si no hay ninguna pila IPv4 en el equipo local y se especificó una dirección IPv4 en el miembro AddressMIB_UNICASTIPADDRESS_ROW apuntado por el parámetro Row o no hay ninguna pila IPv6 en el equipo local y se especificó una dirección IPv6 en el miembro Address .
Otros	Use FormatMessage para obtener la cadena de mensaje del error devuelto.

Comentarios

La función SetUnicastIpAddressEntry se define en Windows Vista y versiones posteriores.

La función GetUnicastIpAddressEntry se usa normalmente para recuperar una entrada de estructura de MIB_UNICASTIPADDRESS_ROW existente que se va a modificar. Después, una aplicación puede cambiar los miembros de la entrada MIB_UNICASTIPADDRESS_ROW que desea modificar y, a continuación, llamar a la función SetUnicastIpAddressEntry .

Una aplicación puede llamar a la función InitializeUnicastIpAddressEntry para inicializar los miembros de una entrada de estructura de MIB_UNICASTIPADDRESS_ROW con valores predeterminados antes de realizar cambios. Sin embargo, la aplicación normalmente guardaría el miembro InterfaceLuid o InterfaceIndex antes de llamar a InitializeUnicastIpAddressEntry y restaurar uno de estos miembros después de la llamada.

El miembro Address de la estructura MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row debe inicializarse en una dirección y familia IPv4 de unidifusión válida o IPv6. Además, se debe inicializar al menos uno de los siguientes miembros de la estructura MIB_UNICASTIPADDRESS_ROW que apunta al parámetro Row : InterfaceLuid o InterfaceIndex.

Los campos se usan en el orden indicado anteriormente. Por lo tanto, si se especifica InterfaceLuid , este miembro se usa para determinar la interfaz. Si no se estableció ningún valor para el miembro InterfaceLuid (los valores de este miembro se establecieron en cero), el miembro InterfaceIndex se usa a continuación para determinar la interfaz.

Si el miembro OnLinkPrefixLength del MIB_UNICASTIPADDRESS_ROW al que apunta el parámetro Row se establece en 255, SetUnicastIpAddressEntry establecerá las propiedades de dirección IP de unidifusión para que el miembro OnLinkPrefixLength sea igual a la longitud de la dirección IP. Por lo tanto, para una dirección IPv4 de unidifusión, OnLinkPrefixLength se establece en 32 y OnLinkPrefixLength se establece en 128 para una dirección IPv6 de unidifusión. Si esto da como resultado la máscara de subred incorrecta para una dirección IPv4 o el prefijo de vínculo incorrecto para una dirección IPv6, la aplicación debe establecer este miembro en el valor correcto antes de llamar a SetUnicastIpAddressEntry.

Los miembros DadState, ScopeId y CreationTimeStamp de la estructura MIB_UNICASTIPADDRESS_ROWa la que apunta row se omiten cuando se llama a la función SetUnicastIpAddressEntry . La pila de red establece estos miembros y no se puede cambiar mediante la función SetUnicastIpAddressEntry . El miembro ScopeId viene determinado automáticamente por la interfaz en la que se agregó la dirección.

Un usuario que ha iniciado sesión como miembro del grupo Administradores solo puede llamar a la función SetUnicastIpAddressEntry . Si un usuario llama a SetUnicastIpAddressEntry que no es miembro del grupo Administradores, se producirá un error en la llamada a la función y se devolverá ERROR_ACCESS_DENIED .

La función SetUnicastIpAddressEntry también puede producir un error debido al control de cuentas de usuario (UAC) en Windows Vista y versiones posteriores. Si un usuario inicia sesión como miembro del grupo Administradores que no sea el administrador integrado, esta llamada producirá un error a menos que la aplicación se haya marcado en el archivo de manifiesto con un valor requestedExecutionLevel establecido en requireAdministrator. Si la aplicación carece de este archivo de manifiesto, un usuario que inició sesión como miembro del grupo Administradores que no sea el administrador integrado debe ejecutar la aplicación en un shell mejorado como administrador integrado (administrador de RunAs) para que esta función se realice correctamente.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	netioapi.h (incluya Iphlpapi.h)
Library	Iphlpapi.lib
Archivo DLL	Iphlpapi.dll