Función NotifyUnicastIpAddressChange

Artículo
03/08/2023

La función NotifyUnicastIpAddressChange registra el controlador 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

NETIOAPI_API NotifyUnicastIpAddressChange(
  _In_    ADDRESS_FAMILY                     Family,
  _In_    PUNICAST_IPADDRESS_CHANGE_CALLBACK Callback,
  _In_    PVOID                              CallerContext,
  _In_    BOOLEAN                            InitialNotification,
  _Inout_ HANDLE                             *NotificationHandle
);

Parámetros

Familia [in]
Familia de direcciones en la que se va a registrar el controlador para recibir 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 de PF_ son idénticas (por ejemplo, AF_INET y PF_INET), por lo que puede usar cualquiera de las constantes.

En Windows Vista y versiones posteriores de los sistemas operativos Windows, los valores posibles para el parámetro Family se definen en el archivo de encabezado Ws2def.h. Tenga en cuenta que el archivo de encabezado Ws2def.h se incluye automáticamente en Netioapi.h y nunca debe usar Ws2def.h directamente.

Actualmente se admiten los siguientes valores para la familia de direcciones:
- AF_INET
  Familia de direcciones IPv4. Cuando se especifica este valor, la función registra el controlador solo para las notificaciones de cambio de dirección IPv4 de unidifusión.
- AF_INET6
  Familia de direcciones IPv6. Cuando se especifica este valor, la función registra el controlador solo para las notificaciones de cambio de dirección IPv6 de unidifusión.
- AF_UNSPEC
  No se especifica la familia de direcciones. Cuando se especifica este valor, la función registra el controlador para las notificaciones de cambio de dirección IPv4 e IPv6 de unidifusión.
Devolución de llamada [in]
Puntero a la función que se va a llamar cuando se produce un cambio. Se llama a esta función cuando se recibe una notificación de dirección IP de unidifusión.
CallerContext [in]
Contexto de usuario que se pasa a la función de devolución de llamada especificada en el parámetro Callback cuando se recibe una notificación de interfaz.
InitialNotification [in]
Valor que indica si se debe llamar a la devolución de llamada inmediatamente después de que se complete el registro para la notificación de cambio. Esta notificación inicial no indica que se produjo un cambio en una dirección IP de unidifusión. Este parámetro proporciona confirmación de que la devolución de llamada está registrada.
NotificationHandle [in, out]
Puntero que se usa para devolver un identificador que el controlador puede usar más adelante para anular el registro de la notificación de cambio del controlador. 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

NotifyUnicastIpAddressChange devuelve STATUS_SUCCESS si la función se realiza correctamente.

Si se produce un error en la función, NotifyUnicastIpAddressChange devuelve 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.
STATUS_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.
STATUS_NOT_ENOUGH_MEMORY	No había memoria suficiente.
Otros	Use la función FormatMessage para obtener la cadena de mensaje para el error devuelto.

Observaciones

El controlador debe establecer el parámetro Family 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 que se pasan a la función de devolución de llamada incluyen lo siguiente.

Parámetro	Descripción
IN PVOID CallerContext	El parámetro CallerContext que se pasa a la función NotifyUnicastIpAddressChange cuando registra el controlador para las notificaciones de cambio.
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 que se pasa en el parámetro NotificationType a la función de devolución de llamada se establece en MibInitialNotification. Esta situación solo puede producirse si el parámetro InitialNotification que se pasa a NotifyUnicastIpAddressChange se estableció en TRUE al registrar el controlador para recibir notificaciones de cambio.
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 .

Para anular el registro del controlador para las notificaciones de cambio, llame a la función CancelMibChangeNotify2 , pasando el parámetro NotificationHandle que NotifyUnicastIpAddressChange devuelve.

Requisitos

Plataforma de destino	Universal
Versión	Disponible en Windows Vista y versiones posteriores de los sistemas operativos Windows.
Encabezado	Netioapi.h (incluya Netioapi.h)
Biblioteca	Netio.lib
IRQL	< DISPATCH_LEVEL