Función NotifyUnicastIpAddressChange (netioapi.h)

Artículo
08/25/2023

La función NotifyUnicastIpAddressChange se registra para recibir notificaciones de cambios en todas las interfaces IP de unidifusión, direcciones IPv4 de unidifusión o direcciones IPv6 de unidifusión en un equipo local.

Sintaxis

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyUnicastIpAddressChange(
  [in]      ADDRESS_FAMILY                     Family,
  [in]      PUNICAST_IPADDRESS_CHANGE_CALLBACK Callback,
  [in]      PVOID                              CallerContext,
  [in]      BOOLEAN                            InitialNotification,
  [in, out] HANDLE                             *NotificationHandle
);

Parámetros

[in] Family

Familia de direcciones en la que se va a registrar las notificaciones de cambio.

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énticas (por ejemplo, AF_INET y PF_INET), por lo que se puede usar cualquiera de las constantes.

En el Windows SDK publicado para Windows Vista y versiones posteriores, la organización de 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_INET	Regístrese solo para las notificaciones de cambio de dirección IPv4 de unidifusión.
AF_INET6	Regístrese solo para las notificaciones de cambio de dirección IPv6 de unidifusión.
AF_UNSPEC	Regístrese para las notificaciones de cambio de dirección IPv4 e IPv6 de unidifusión.

[in] Callback

Puntero a la función que se va a llamar cuando se produce un cambio. Esta función se invocará cuando se reciba una notificación de dirección IP de unidifusión.

[in] CallerContext

Contexto de usuario pasado a la función de devolución de llamada especificada en el parámetro Callback cuando se recibe una notificación de interfaz.

[in] InitialNotification

Valor que indica si la devolución de llamada se debe invocar inmediatamente después de que se complete el registro para la notificación de cambio. Esta notificación inicial no indica que se ha producido un cambio en una dirección IP de unidifusión. El propósito de este parámetro para proporcionar confirmación de que la devolución de llamada está registrada.

[in, out] NotificationHandle

Puntero usado para devolver un identificador que se puede usar más adelante para anular el registro de la notificación de cambio. Si se ejecuta correctamente, se devuelve un identificador de notificación en este parámetro. Si se produce un error, se devuelve NULL .

Valor devuelto

Si la función se ejecuta 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_INVALID_HANDLE	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 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 para el error devuelto.

Comentarios

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

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

La invocación de la función de devolución de llamada especificada en el parámetro Callback se serializa. La función de devolución de llamada 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 NotifyUnicastIpAddressChange al registrarse para recibir notificaciones.
IN PMIB_UNICASTIPADDRESS_ROW Fila OPCIONAL	Puntero a la entrada MIB_UNICASTIPADDRESS_ROW para la dirección IP de unidifusión que se cambió. Este parámetro es un puntero NULL cuando el valor de MIB_NOTIFICATION_TYPE pasado en el parámetro NotificationType a la función de devolución de llamada se establece en MibInitialNotification. Esto solo puede ocurrir si el parámetro InitialNotification pasado a NotifyUnicastIpAddressChange se estableció en TRUE al registrarse para recibir notificaciones.
IN MIB_NOTIFICATION_TYPE NotificationType	Tipo de notificación. Este miembro puede ser uno de los valores del tipo de enumeración MIB_NOTIFICATION_TYPE definido en el archivo de encabezado Netioapi.h .

La función de devolución de llamada especificada en el parámetro Callback debe implementarse en el mismo proceso que la aplicación que llama a la función NotifyUnicastIpAddressChange . 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 NotifyUnicastIpAddressChange para registrarse para recibir notificaciones de cambio.

Cuando se recibe la función de devolución de llamada cuando se produce un cambio y el parámetro Row no es NULL, el puntero a la estructura de MIB_UNICASTIPADDRESS_ROW pasada en el parámetro Row contiene datos incompletos. La información devuelta en la estructura MIB_UNICASTIPADDRESS_ROW solo es suficiente información que una aplicación puede llamar a la función GetUnicastIpAddressEntry para consultar información completa sobre la dirección IP que cambió. Cuando se recibe la función de devolución de llamada, una aplicación debe asignar una estructura de MIB_UNICASTIPADDRESS_ROW e inicializarla con los miembros Address, InterfaceLuid e InterfaceIndex en la estructura MIB_UNICASTIPADDRESS_ROW a la que apunta el parámetro Row recibido. Se debe pasar un puntero a esta estructura de MIB_UNICASTIPADDRESS_ROW recién inicializada a la función GetUnicastIpAddressEntry para recuperar información completa sobre la dirección IP de unidifusión que se cambió.

El sistema operativo administra la memoria a la que apunta el parámetro Row utilizado en las indicaciones de devolución de llamada. Una aplicación que recibe una notificación nunca debe intentar liberar la memoria a la que apunta el parámetro Row .

Una vez que se llama a la función NotifyUnicastIpAddressChange para registrarse para recibir notificaciones de cambios, 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 cambios 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 NotifyUnicastIpAddressChange.

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 (include Iphlpapi.h)
Library	Iphlpapi.lib
Archivo DLL	Iphlpapi.dll