Función NotifyRouteChange2 (netioapi.h)

Artículo
03/15/2023

La función NotifyRouteChange2 se registra para recibir notificaciones de cambios en las entradas de ruta IP de un equipo local.

Sintaxis

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyRouteChange2(
  [in]      ADDRESS_FAMILY             AddressFamily,
  [in]      PIPFORWARD_CHANGE_CALLBACK Callback,
  [in]      PVOID                      CallerContext,
  [in]      BOOLEAN                    InitialNotification,
  [in, out] HANDLE                     *NotificationHandle
);

Parámetros

[in] AddressFamily

Familia de direcciones en la que se va a registrar para recibir notificaciones de cambios.

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 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_INET	Regístrese solo para las notificaciones de cambio de ruta IPv4.
AF_INET6	Regístrese solo para las notificaciones de cambio de ruta IPv6.
AF_UNSPEC	Regístrese para las notificaciones de cambio de ruta IPv4 e IPv6.

[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 ruta IP.

[in] CallerContext

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

[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 cambios. Esta notificación inicial no indica que se ha producido un cambio en una entrada de ruta IP. El propósito de este parámetro para proporcionar confirmación de que la devolución de llamada está registrada.

[in, out] NotificationHandle

Puntero que se usa 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 realiza 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	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 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 NotifyRouteChange2 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 NotifyRouteChange2 al registrarse para recibir notificaciones.
IN PMIB_IPFORWARD_ROW2 Row OPTIONAL	Puntero a la entrada de MIB_IPFORWARD_ROW2 para la entrada de ruta IP 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 NotifyRouteChange2 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 NotifyRouteChange2 . 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 NotifyRouteChange2 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 MIB_IPFORWARD_ROW2 pasada en el parámetro Row contiene datos incompletos. La información devuelta en la estructura de MIB_IPFORWARD_ROW2 solo es suficiente información que una aplicación puede llamar a la función GetIpForwardEntry2 para consultar información completa sobre la ruta IP que cambió. Cuando se recibe la función de devolución de llamada, una aplicación debe asignar una estructura de MIB_IPFORWARD_ROW2 e inicializarla con los miembros DestinationPrefix, NextHop, InterfaceLuid e InterfaceIndex en la estructura MIB_IPFORWARD_ROW2 a la que apunta el parámetro Row recibido. Se debe pasar un puntero a esta estructura de MIB_IPFORWARD_ROW2 recién inicializada a la función GetIpForwardEntry2 para recuperar información completa sobre la ruta IP 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 NotifyRouteChange2 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 anular explícitamente el registro de una aplicación para 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 NotifyRouteChange2.

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


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