Función NotifyAddrChange (iphlpapi.h)

Artículo
08/24/2023

La función NotifyAddrChange hace que se envíe una notificación al autor de la llamada cada vez que se produce un cambio en la tabla que asigna direcciones IPv4 a interfaces.

Sintaxis

IPHLPAPI_DLL_LINKAGE DWORD NotifyAddrChange(
  [out] PHANDLE      Handle,
  [in]  LPOVERLAPPED overlapped
);

Parámetros

[out] Handle

Puntero a una variable HANDLE que recibe un identificador de archivo para su uso en una llamada posterior a la función GetOverlappedResult .

Advertencia No cierre este identificador y no lo asocie a un puerto de finalización.

[in] overlapped

Puntero a una estructura SUPERPUESTA que notifica al autor de la llamada cualquier cambio en la tabla que asigna direcciones IP a interfaces.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se NO_ERROR si el autor de la llamada especifica NULL para los parámetros Handle y superpuestos . Si el autor de la llamada especifica parámetros que no son NULL , se ERROR_IO_PENDING el valor devuelto de correcto.

Si se produce un error en la función, use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Código devuelto	Descripción
ERROR_CANCELLED	El contexto se está anulando, por lo que la llamada se canceló inmediatamente.
ERROR_INVALID_PARAMETER	Se pasó un parámetro no válido. Este error se devuelve si los parámetros Handle y superpuestos no son NULL, pero el proceso de llamada no puede escribir la memoria especificada por los parámetros de entrada. Este error también se devuelve si el cliente ya ha realizado una solicitud de notificación de cambio, por lo que se producirá un error en esta solicitud duplicada.
ERROR_NOT_ENOUGH_MEMORY	No había suficiente memoria disponible para completar la operación.
ERROR_NOT_SUPPORTED	Este error se devuelve en las versiones de Windows en las que esta función no es compatible, como Windows 98/95 y Windows NT 4.0.

Comentarios

The
Se puede llamar a la función NotifyAddrChange de dos maneras:

Método sincrónico
Método asincrónico

Si el autor de la llamada especifica NULL para los parámetros Handle y superpuestos , la llamada a NotifyAddrChange es sincrónica y se bloqueará hasta que se produzca un cambio de dirección IP. En este caso, si se produce un cambio, la función NotifyAddrChange se completa para indicar que se ha producido un cambio.

Si la función NotifyAddrChange se llama sincrónicamente, se enviará una notificación en el siguiente cambio de dirección IPv4 hasta que finalice la aplicación.

Si el autor de la llamada especifica una variable de controlador y una estructura SUPERPUESTA , la llamada a la función NotifyAddrChange es asincrónica y el autor de la llamada puede usar el identificador devuelto con la estructura SUPERPUESTA para recibir notificaciones asincrónicas de cambios de dirección IPv4 mediante la función GetOverlappedResult . Consulte los temas siguientes para obtener información sobre el uso de la estructura handle y OVERLAPPED para recibir notificaciones:

La función CancelIPChangeNotify cancela la notificación de la dirección IPv4 y enruta los cambios solicitados anteriormente con llamadas correctas a las funciones NotifyAddrChange o NotifyRouteChange .

Una vez que se ha notificado un cambio a una aplicación, la aplicación puede llamar a la función GetIpAddrTable o GetAdaptersAddresses para recuperar la tabla de direcciones IPv4 para determinar qué ha cambiado. Si se notifica a la aplicación y se requiere una notificación para el siguiente cambio, se debe volver a llamar a la función NotifyAddrChange .

Si la función NotifyAddrChange se llama de forma asincrónica, se enviará una notificación en el siguiente cambio de dirección IPv4 hasta que la aplicación cancele la notificación llamando a la función CancelIPChangeNotify o finaliza la aplicación. Si la aplicación finaliza, el sistema cancelará automáticamente el registro de la notificación. Todavía se recomienda que una aplicación cancele explícitamente cualquier notificación antes de que finalice.

Cualquier registro de una notificación no persiste en un apagado o reinicio del sistema.

En Windows Vista y versiones posteriores, la función NotifyIpInterfaceChange se puede usar para registrarse para recibir notificaciones de cambios en las interfaces IPv4 e IPv6 del equipo local.

Ejemplos

En el ejemplo siguiente se espera a que se produzca un cambio en la tabla que asigna direcciones IP a interfaces.

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <windows.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

void main()
{
  OVERLAPPED overlap;
  DWORD ret;
    
  HANDLE hand = NULL;
  overlap.hEvent = WSACreateEvent();

  ret = NotifyAddrChange(&hand, &overlap);

  if (ret != NO_ERROR)
  {
    if (WSAGetLastError() != WSA_IO_PENDING)
    {
      printf("NotifyAddrChange error...%d\n", WSAGetLastError());            
      return;
    }
  }

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("IP Address table changed..\n");
}

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	iphlpapi.h
Library	Iphlpapi.lib
Archivo DLL	Iphlpapi.dll