Función NotifyUnicastIpAddressChange (netioapi.h)
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.
[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 interno en el que se encontró un identificador no válido. |
|
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. |
|
No había memoria suficiente. |
|
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 |
Consulte también
Referencia de la función auxiliar de IP
InitializeUnicastIpAddressEntry