Función NotifyRouteChange (iphlpapi.h)

Artículo
08/24/2023

La función NotifyRouteChange hace que se envíe una notificación al autor de la llamada cada vez que se produzca un cambio en la tabla de enrutamiento IPv4.

Sintaxis

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

Parámetros

[out] Handle

Puntero a una variable HANDLE que recibe un identificador que se va a usar en la notificación asincrónica.

[in] overlapped

Puntero a una estructura SUPERPUESTA que notifica al autor de la llamada cualquier cambio en la tabla de enrutamiento.

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 NotifyRouteChange 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 NotifyRouteChange es sincrónica y se bloqueará hasta que se produzca un cambio de tabla de enrutamiento de IPv4. En este caso, si se produce un cambio, la función NotifyRouteChange se completa para indicar que se ha producido un cambio.

Si la función NotifyRouteChange se llama de forma sincrónica, se enviará una notificación en el siguiente cambio de enrutamiento IPv4 hasta que finalice la aplicación.

Si el autor de la llamada especifica una variable de identificador y una estructura SUPERPUESTA , el autor de la llamada puede usar el identificador devuelto con la estructura SUPERPUESTA para recibir notificaciones asincrónicas de cambios en la tabla de enrutamiento IPv4. Consulte los temas siguientes para obtener información sobre el uso de la estructura handle y OVERLAPPED para recibir notificaciones:

Si la aplicación recibe una notificación y requiere una notificación para el siguiente cambio, se debe volver a llamar a la función NotifyRouteChange .

La función CancelIPChangeNotify cancela la notificación de la dirección IP y los cambios de ruta 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 GetIpForwardTable o GetIpForwardTable2 para recuperar la tabla de enrutamiento IPv4 para determinar lo que 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 NotifyRouteChange .

Si se llama a la función NotifyRouteChange de forma asincrónica, se enviará una notificación en el siguiente cambio de ruta 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, se puede usar la función NotifyRouteChange2 para registrarse para recibir notificaciones de cambios en la tabla de enrutamiento IPv6 del equipo local.

Ejemplos

En el ejemplo siguiente se espera a que se produzca un cambio en la tabla de enrutamiento de IP.

#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 = NotifyRouteChange(&hand, &overlap);

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

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("Routing 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