Función CreateUnicastIpAddressEntry

Artículo
03/08/2023

La función CreateUnicastIpAddressEntry agrega una nueva entrada de dirección IP de unidifusión en el equipo local.

Sintaxis

NETIOAPI_API CreateUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

Parámetros

Fila [in]
Puntero a una entrada de estructura MIB_UNICASTIPADDRESS_ROW para una entrada de dirección IP de unidifusión.

Valor devuelto

CreateUnicastIpAddressEntry devuelve STATUS_SUCCESS si la función se ejecuta correctamente.

Si se produce un error en la función, CreateUnicastIpAddressEntry devuelve uno de los siguientes códigos de error:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se ha transferido 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 de la estructura MIB_UNICASTIPADDRESS_ROW a la 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 e InterfaceIndex de la estructura de MIB_UNICASTIPADDRESS_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 las siguientes situaciones: El miembro ValidLifetime es menor que el miembro PreferredLifetime . El miembro PrefixOrigin se establece en IpPrefixOriginUnchanged y el sufijoOrigin no se establece en IpSuffixOriginUnchanged. El miembro PrefixOrigin no se establece en IpPrefixOriginUnchanged y el sufijoOrigin se establece en IpSuffixOriginUnchanged. El miembro PrefixOrigin no se establece en un valor de la enumeración NL_PREFIX_ORIGIN . El miembro SuffixOrigin no se establece en un valor de la enumeración NL_SUFFIX_ORIGIN. El miembro OnLinkPrefixLength se establece 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). Para conocer los posibles valores de las enumeraciones NL_PREFIX_ORIGIN y NL_SUFFIX_ORIGIN, consulte MIB_UNICASTIPADDRESS_ROW.
STATUS_NOT_FOUND	No se encuentra la interfaz especificada. Este error se devuelve si la función no encuentra la interfaz de red especificada por el miembro InterfaceLuid o InterfaceIndex de la estructura MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row .
STATUS_NOT_SUPPORTED	No se admite la solicitud. Este error se devuelve si no hay ninguna pila IPv4 ubicada en el equipo local y se especificó una dirección IPv4 en el miembro Address de la estructura de MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row , o si no hay ninguna pila IPv6 ubicada en el equipo local y se especificó una dirección IPv6 en el miembro Address .
ERROR_OBJECT_ALREADY_EXISTS	El objeto ya existe. Este error se devuelve si el miembro Address de la estructura MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row es un duplicado de una dirección IP de unidifusión existente en la interfaz especificada por el miembro InterfaceLuid o InterfaceIndex del MIB_UNICASTIPADDRESS_ROW.
Otros	Use la función FormatMessage para obtener la cadena de mensaje para el error devuelto.

Comentarios

Use la función InitializeUnicastIpAddressEntry para inicializar los miembros de una entrada de estructura de MIB_UNICASTIPADDRESS_ROW con valores predeterminados. A continuación, un controlador puede cambiar los miembros de la entrada MIB_UNICASTIPADDRESS_ROW que desea modificar y, a continuación, llamar a la función CreateUnicastIpAddressEntry .

En la entrada, el controlador debe inicializar los siguientes miembros de la estructura MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row .

Dirección
Establézcalo en una dirección iPv4 o IPv6 válida y una familia.
InterfaceLuid o InterfaceIndex
Estos miembros se usan en el orden que se muestra anteriormente. Por lo tanto, si se especifica InterfaceLuid , este miembro se usa para determinar la interfaz a la que agregar la dirección IP de unidifusión. Si no se estableció ningún valor para el miembro InterfaceLuid (el valor de este miembro se estableció en cero), el miembro InterfaceIndex se usará a continuación para determinar la interfaz.

Si el miembro OnLinkPrefixLength de la estructura de MIB_UNICASTIPADDRESS_ROW al que apunta el parámetro Row se establece en 255, CreateUnicastIpAddressEntry agrega la nueva dirección IP de unidifusión con el miembro OnLinkPrefixLength establecido 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 esta configuración daría 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, el controlador debe establecer el miembro OnLinkPrefixLength en el valor correcto antes de llamar a CreateUnicastIpAddressEntry.

Si se crea una dirección IP de unidifusión con el miembro OnLinkPrefixLength establecido incorrectamente, el controlador puede cambiar la dirección IP llamando a SetUnicastIpAddressEntry con el miembro OnLinkPrefixLength establecido en el valor correcto.

Los miembros DadState, ScopeId y CreationTimeStamp de la estructura MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row se omiten cuando se llama a la función CreateUnicastIpAddressEntry . La pila de red establece estos miembros. El miembro ScopeId se determina automáticamente por la interfaz en la que se agrega la dirección.

Se produce un error en la función CreateUnicastIpAddressEntry si la dirección IP de unidifusión que se pasa en el miembro Address de la estructura de MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row es un duplicado de una dirección IP de unidifusión existente en la interfaz. Tenga en cuenta que el controlador puede agregar una dirección IP de bucle invertido a una interfaz de bucle invertido solo mediante la función CreateUnicastIpAddressEntry .

La dirección IP de unidifusión que se pasa en el miembro Address de la estructura MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row no se puede usar inmediatamente. La dirección IP se puede usar después de que el proceso de detección de direcciones duplicadas se haya completado correctamente. El proceso de detección de direcciones duplicadas puede tardar varios segundos en completarse, ya que se deben enviar paquetes IP y se deben esperar posibles respuestas. Para IPv6, el proceso de detección de direcciones duplicadas suele tardar aproximadamente 1 segundo. Para IPv4, el proceso de detección de direcciones duplicadas suele tardar unos 3 segundos.

Después de que un controlador llame a la función CreateUnicastIpAddressEntry , puede usar los métodos siguientes para determinar si una dirección IP sigue siendo utilizable:

Uso del sondeo y la función GetUnicastIpAddressEntry
Una vez que la llamada a la función CreateUnicastIpAddressEntry se devuelve correctamente, pause durante 1 a 3 segundos (dependiendo de si se crea una dirección IPv6 o IPv4) para permitir el tiempo de finalización correcta del proceso de detección de direcciones de duplicación. A continuación, llame a GetUnicastIpAddressEntry para recuperar la estructura de MIB_UNICASTIPADDRESS_ROW actualizada y examinar el valor del miembro DadState. Si el valor del miembro DadState se establece en IpDadStatePreferred, la dirección IP ahora se puede usar. Si el valor del miembro DadState se establece en IpDadStateTentative, la detección de direcciones duplicadas aún no se ha completado. En este caso, llame de nuevo a la función GetUnicastIpAddressEntry cada 0,5 segundos mientras el miembro DadState todavía está establecido en IpDadStateTentative. Si el valor del miembro DadState devuelve con algún valor distinto de IpDadStatePreferred o IpDadStateTentative, se ha producido un error en la detección de direcciones duplicadas y la dirección IP no se puede usar.
Llame a una de las funciones de notificación NotifyXxx del asistente de IP para configurar una notificación asincrónica para cuando cambie una dirección.
Una vez que la llamada a la función CreateUnicastIpAddressEntry se devuelve correctamente, llame a la función NotifyUnicastIpAddressChange para registrar el controlador para recibir notificaciones de cambios en direcciones IP de unidifusión IPv6 o IPv4, en función del tipo de dirección IP que se está creando. Cuando se recibe una notificación para la dirección IP que se está creando, llame a la función GetUnicastIpAddressEntry para recuperar el miembro DadState . Si el valor del miembro DadState se establece en IpDadStatePreferred, la dirección IP ahora se puede usar. Si el valor del miembro DadState se establece en IpDadStateTentative, la detección de direcciones duplicadas aún no se ha completado y el controlador debe esperar notificaciones futuras. Si el valor del miembro DadState devuelve con algún valor distinto de IpDadStatePreferred o IpDadStateTentative, se ha producido un error en la detección de direcciones duplicadas y la dirección IP no se puede usar.

Si, durante el proceso de detección de direcciones duplicadas, el medio se desconecta y, a continuación, se vuelve a conectar, se reinicia el proceso de detección de direcciones duplicadas. Por lo tanto, el tiempo para completar el proceso puede aumentar más allá del valor típico de 1 segundo para IPv6 o 3 segundos para IPv4.

Requisitos

Plataforma de destino	Universal
Versión	Disponible en Windows Vista y versiones posteriores de los sistemas operativos Windows.
Encabezado	Netioapi.h (incluye Netioapi.h)
Biblioteca	Netio.lib
IRQL	< DISPATCH_LEVEL