Función NotifyStableUnicastIpAddressTable (netioapi.h)

Artículo
03/15/2023

La función NotifyStableUnicastIpAddressTable recupera la tabla de direcciones IP de unidifusión estable en un equipo local.

Sintaxis

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
  [in]      ADDRESS_FAMILY                           Family,
  [in, out] PMIB_UNICASTIPADDRESS_TABLE              *Table,
  [in]      PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  [in]      PVOID                                    CallerContext,
  [in, out] HANDLE                                   *NotificationHandle
);

Parámetros

[in] Family

Familia de direcciones que se va a recuperar.

Los valores posibles para la familia de direcciones se enumeran en el archivo de encabezado Winsock2.h . Tenga en cuenta que los valores de la familia de direcciones AF_ y las constantes de familia de protocolos PF_ son idénticos (por ejemplo, AF_INET y PF_INET), por lo que se puede usar cualquier constante.

En el Windows SDK publicado para Windows Vista y versiones posteriores, la organización de los archivos de encabezado ha cambiado y los valores posibles para este miembro se definen en el archivo de encabezado Ws2def.h. Tenga en cuenta que el archivo de encabezado Ws2def.h se incluye automáticamente en Winsock2.h y nunca se debe usar directamente.

Los valores admitidos actualmente son AF_INET, AF_INET6 y AF_UNSPEC.

Valor	Significado
AF_UNSPEC 0	La familia de direcciones no está especificada. Cuando se especifica este parámetro, la función recupera la tabla de direcciones IP de unidifusión estable que contiene entradas IPv4 e IPv6.
AF_INET 2	Familia de direcciones del Protocolo de Internet versión 4 (IPv4). Cuando se especifica este parámetro, la función recupera la tabla de direcciones IP de unidifusión estable que contiene solo entradas IPv4.
AF_INET6 23	Familia de direcciones del Protocolo de Internet versión 6 (IPv6). Cuando se especifica este parámetro, la función recupera la tabla de direcciones IP de unidifusión estable que contiene solo entradas IPv6.

[in, out] Table

Puntero a una estructura MIB_UNICASTIPADDRESS_TABLE . Cuando NotifyStableUnicastIpAddressTable se realiza correctamente, este parámetro devuelve la tabla de direcciones IP de unidifusión estable en el equipo local.

Cuando NotifyStableUnicastIpAddressTable devuelve ERROR_IO_PENDING que indica que la solicitud de E/S está pendiente, la tabla de direcciones IP de unidifusión estable se devuelve a la función en el parámetro CallerCallback .

[in] CallerCallback

Puntero a la función que se va a llamar con la tabla de direcciones IP de unidifusión estable. Esta función se invocará si NotifyStableUnicastIpAddressTable devuelve ERROR_IO_PENDING, lo que indica que la solicitud de E/S está pendiente.

[in] CallerContext

Contexto de usuario pasado a la función de devolución de llamada especificada en el parámetro CallerCallback cuando la tabla de direcciones IP de unidifusión estable está disponible.

[in, out] NotificationHandle

Puntero que se usa para devolver un identificador que se puede usar para cancelar la solicitud para recuperar la tabla de direcciones IP de unidifusión estable. Este parámetro se devuelve si el valor devuelto de NotifyStableUnicastIpAddressTable es ERROR_IO_PENDING que indica que la solicitud de E/S está pendiente.

Valor devuelto

Si la función se realiza correctamente inmediatamente, el valor devuelto se NO_ERROR y la tabla IP de unidifusión estable se devuelve en el parámetro Table .

Si la solicitud de E/S está pendiente, la función devuelve ERROR_IO_PENDING y se llama a la función a la que apunta el parámetro CallerCallback cuando la solicitud de E/S se ha completado con la tabla estable de direcciones IP de unidifusión.

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_INVALID_HANDLE	Se produjo un error interno en el que se encontró un identificador no válido.
ERROR_INVALID_PARAMETER	Se pasó un parámetro no válido a la función. Este error se devuelve si el parámetro Table era un puntero NULL , el parámetro NotificationHandle era un puntero NULL o el parámetro Family no se AF_INET, AF_INET6 o AF_UNSPEC.
ERROR_NOT_ENOUGH_MEMORY	No había memoria suficiente.
Otros	Use FormatMessage para obtener la cadena de mensaje del error devuelto.

Comentarios

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

Si la función NotifyStableUnicastIpAddressTable se realiza correctamente inmediatamente, el valor devuelto se NO_ERROR y la tabla IP de unidifusión estable se devuelve en el parámetro Table . La aplicación que realiza la llamada debe liberar la memoria a la que apunta el parámetro Table mediante la función FreeMibTable cuando ya no se necesita la información de MIB_UNICASTIPADDRESS_TABLE .

Todas las direcciones IP de unidifusión excepto las direcciones de marcado a petición solo se consideran estables si están en el estado preferido. Para una entrada de dirección IP de unidifusión normal, esto correspondería a un miembro dadState del MIB_UNICASTIPADDRESS_ROW de la dirección IP establecida en IpDadStatePreferred. Cada dirección de marcado a petición define su propia métrica de estabilidad. Actualmente, la única dirección de marcado a petición que esta función considera es la dirección IP de unidifusión que usa el cliente teredo en el equipo local.

El parámetro Family debe establecerse en AF_INET, AF_INET6 o AF_UNSPEC.

Cuando NotifyStableUnicastIpAddressTable se realiza correctamente y devuelve NO_ERROR, el parámetro Table devuelve la tabla de direcciones IP de unidifusión estable en el equipo local.

La función NotifyStableUnicastIpAddressTable se usa principalmente por las aplicaciones que usan el cliente Teredo.

Si la dirección IP de unidifusión usada por Teredo está disponible en el equipo local, pero no en el estado estable (calificado), NotifyStableUnicastIpAddressTable devuelve ERROR_IO_PENDING y la tabla de direcciones IP de unidifusión estable se devuelve finalmente llamando a la función en el parámetro CallerCallback . Si la dirección Teredo no está disponible o está en estado estable y las demás direcciones IP de unidifusión están en un estado estable, la función del parámetro CallerCallback nunca se invocará.

La función de devolución de llamada especificada en el parámetro CallerCallback debe definirse como una función de tipo VOID. Los parámetros pasados a la función de devolución de llamada incluyen lo siguiente:

Parámetro	Descripción
IN PVOID CallerContext	El parámetro CallerContext pasado a la función NotifyStableUnicastIpAddressTable al registrarse para recibir notificaciones.
IN PMIB_UNICASTIPADDRESS_TABLE AddressTable	Puntero a un MIB_UNICASTIPADDRESS_TABLE que contiene la tabla de direcciones IP de unidifusión estable en el equipo local.

La función de devolución de llamada especificada en el parámetro CallerCallback debe implementarse en el mismo proceso que la aplicación que llama a la función NotifyStableUnicastIpAddressTable . Si la función de devolución de llamada está en un archivo DLL independiente, el archivo DLL debe cargarse antes de llamar a la función NotifyStableUnicastIpAddressTable para registrarse para las notificaciones de cambio.

El sistema operativo asigna la memoria a la que apunta el parámetro AddressTable utilizado en una indicación de devolución de llamada. Una aplicación que recibe una notificación debe liberar la memoria a la que apunta el parámetro AddressTable mediante la función FreeMibTable cuando ya no se necesita la información de MIB_UNICASTIPADDRESS_TABLE .

Una vez que se llama a la función NotifyStableUnicastIpAddressTable para registrarse para recibir notificaciones de cambio, estas notificaciones se seguirán enviando hasta que la aplicación anule el registro de las notificaciones de cambio o finalice la aplicación. Si la aplicación finaliza, el sistema anulará automáticamente el registro de las notificaciones de cambios. Todavía se recomienda que una aplicación anule explícitamente el registro de las notificaciones de cambio antes de que finalice.

Cualquier registro de las notificaciones de cambio no persiste si el sistema está apagado o reiniciado.

Para anular el registro de las notificaciones de cambios, llame a la función CancelMibChangeNotify2 pasando el parámetro NotificationHandle devuelto por NotifyStableUnicastIpAddressTable.

Una aplicación no puede realizar una llamada a la función CancelMibChangeNotify2 desde el contexto del subproceso que está ejecutando actualmente la función de devolución de llamada de notificación para el mismo parámetro NotificationHandle . De lo contrario, el subproceso que ejecuta esa devolución de llamada dará como resultado un interbloqueo. Por lo tanto, la función CancelMibChangeNotify2 no debe llamarse directamente como parte de la rutina de devolución de llamada de notificación. En una situación más general, un subproceso que ejecuta la función CancelMibChangeNotify2 no puede poseer un recurso en el que el subproceso que ejecuta una operación de devolución de llamada de notificación esperaría porque daría lugar a un interbloqueo similar. Se debe llamar a la función CancelMibChangeNotify2 desde un subproceso diferente, en el que el subproceso que recibe la devolución de llamada de notificación no tiene dependencias.

Requisitos

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