Función WlanRegisterNotification (wlanapi.h)

Artículo
01/30/2024

Importante

Parte de la información se relaciona con un producto de versión preliminar que puede modificarse sustancialmente antes de su lanzamiento comercial. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.

La función WlanRegisterNotification se usa para registrar y anular el registro de notificaciones en todas las interfaces inalámbricas.

Sintaxis

DWORD WlanRegisterNotification(
  [in]            HANDLE                     hClientHandle,
  [in]            DWORD                      dwNotifSource,
  [in]            BOOL                       bIgnoreDuplicate,
  [in, optional]  WLAN_NOTIFICATION_CALLBACK funcCallback,
  [in, optional]  PVOID                      pCallbackContext,
  [in]            PVOID                      pReserved,
  [out, optional] PDWORD                     pdwPrevNotifSource
);

Parámetros

[in] hClientHandle

Identificador de sesión del cliente, obtenido por una llamada anterior a la función WlanOpenHandle .

[in] dwNotifSource

Los orígenes de notificación que se van a registrar. Estas marcas se pueden combinar. Cuando este parámetro se establece en WLAN_NOTIFICATION_SOURCE_NONE, WlanRegisterNotification anula el registro de las notificaciones en todas las interfaces inalámbricas.

Los valores posibles para este parámetro se definen en los archivos de encabezado Wlanapi.h y L2cmn.h .

En la tabla siguiente se muestran los valores posibles.

Valor	Significado
WLAN_NOTIFICATION_SOURCE_NONE	Anula el registro de las notificaciones.
WLAN_NOTIFICATION_SOURCE_ALL	Registra todas las notificaciones disponibles en la versión del sistema operativo, incluidas las generadas por el módulo 802.1X. Para Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2, establecer dwNotifSource en WLAN_NOTIFICATION_SOURCE_ALL es funcionalmente equivalente a establecer dwNotifSourceen WLAN_NOTIFICATION_SOURCE_ACM.
WLAN_NOTIFICATION_SOURCE_ACM	Registra las notificaciones generadas por el módulo de configuración automática. Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Solo están disponibles las notificaciones de wlan_notification_acm_connection_complete y wlan_notification_acm_disconnected.
WLAN_NOTIFICATION_SOURCE_HNWK	Registra las notificaciones generadas por la red hospedada inalámbrica. Este origen de notificación está disponible en Windows 7 y en Windows Server 2008 R2 con el servicio LAN inalámbrico instalado.
WLAN_NOTIFICATION_SOURCE_ONEX	Registra las notificaciones generadas por 802.1X.
WLAN_NOTIFICATION_SOURCE_MSM	Registra las notificaciones generadas por MSM. Si la marca de WLAN_NOTIFICATION_SOURCE_MSM se establece en dwNotifSource, se requiere la funcionalidad del dispositivo wiFiControl (consulte Declaraciones de funcionalidad de la aplicación). Si no se concede esa funcionalidad, la función devuelve ERROR_ACCESS_DENIED. La solicitud de la funcionalidad del dispositivo wiFiControl requerirá el consentimiento del usuario con respecto al acceso a la ubicación. Para obtener más información, consulte Cambios en el comportamiento de la API para Wi-Fi acceso y ubicación. Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Este valor no se admite.
WLAN_NOTIFICATION_SOURCE_SECURITY	Registra las notificaciones generadas por el módulo de seguridad. Actualmente no se han definido notificaciones para WLAN_NOTIFICATION_SOURCE_SECURITY. Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Este valor no se admite.
WLAN_NOTIFICATION_SOURCE_IHV	Registra las notificaciones generadas por proveedores de hardware independientes (IHV). Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Este valor no se admite.
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	Registra las notificaciones generadas por los servicios de dispositivo.

Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Este parámetro debe establecerse en WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL o WLAN_NOTIFICATION_SOURCE_ACM.

[in] bIgnoreDuplicate

Especifica si se omitirán las notificaciones duplicadas. Si se establece en TRUE, no se enviará una notificación al cliente si es idéntica a la anterior.

Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Este parámetro se omite.

[in, optional] funcCallback

Tipo de WLAN_NOTIFICATION_CALLBACK que define el tipo de función de devolución de llamada de notificación.

Este parámetro puede ser NULL si el parámetro dwNotifSource está establecido en WLAN_NOTIFICATION_SOURCE_NONE para anular el registro de notificaciones en todas las interfaces inalámbricas,

[in, optional] pCallbackContext

Puntero al contexto de cliente que se pasará a la función de devolución de llamada con la notificación.

[in] pReserved

Reservado para uso futuro. Debe establecerse en NULL.

[out, optional] pdwPrevNotifSource

Puntero a los orígenes de notificación registrados anteriormente.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de retorno.

Si la marca de WLAN_NOTIFICATION_SOURCE_MSM se establece en dwNotifSource, se requiere la funcionalidad del dispositivo wiFiControl (consulte Declaraciones de funcionalidad de la aplicación). Si no se concede esa funcionalidad, la función devuelve ERROR_ACCESS_DENIED. La solicitud de la funcionalidad del dispositivo wiFiControl requerirá el consentimiento del usuario con respecto al acceso a la ubicación. Para obtener más información, consulte Cambios en el comportamiento de la API para Wi-Fi acceso y ubicación.

Código devuelto	Descripción
ERROR_INVALID_PARAMETER	Un parámetro es incorrecto. Este error se devuelve si hClientHandle es NULL o no es válido o si pReserved no es NULL.
ERROR_INVALID_HANDLE	El identificador hClientHandle no se encontró en la tabla de identificadores.
ERROR_NOT_ENOUGH_MEMORY	No se pudo asignar memoria para los resultados de la consulta.
ERROR_ACCESS_DENIED	Si la marca de WLAN_NOTIFICATION_SOURCE_MSM está establecida en dwNotifSource, se requiere la funcionalidad del dispositivo wiFiControl (consulte Declaraciones de funcionalidad de la aplicación. Si no se concede esa funcionalidad, la función devuelve ERROR_ACCESS_DENIED. La solicitud de la funcionalidad del dispositivo wiFiControl requerirá el consentimiento del usuario con respecto al acceso a la ubicación. Para obtener más información, consulte Cambios en el comportamiento de la API para Wi-Fi acceso y ubicación.
RPC_STATUS	Varios códigos de error.

Comentarios

Una aplicación usa WlanRegisterNotification para registrar y anular el registro de notificaciones en todas las interfaces inalámbricas. Al registrarse para recibir notificaciones, una aplicación debe proporcionar una función de devolución de llamada a la que apunta el parámetro funcCallback . El prototipo de esta función de devolución de llamada es el WLAN_NOTIFICATION_CALLBACK. Esta función de devolución de llamada recibirá notificaciones registradas para en el parámetro dwNotifSource pasado a la función WlanRegisterNotification . Se llama a la función de devolución de llamada con un puntero a una estructura de WLAN_NOTIFICATION_DATA como primer parámetro que contiene información detallada sobre la notificación. La función de devolución de llamada también recibe un segundo parámetro que contiene un puntero al contexto de cliente pasado en el parámetro pCallbackContext a la función WlanRegisterNotification .

La función WlanRegisterNotification devolverá un error si dwNotifSource es un valor distinto de WLAN_NOTIFICATION_SOURCE_NONE y el cliente no puede proporcionar una función de devolución de llamada.

Una vez registrada, se llamará a la función de devolución de llamada cada vez que haya una notificación disponible hasta que el cliente anule el registro o cierre el identificador.

Cualquier registro para recibir notificaciones causadas por esta función se deshacería automáticamente si la aplicación que realiza la llamada cierra su identificador de llamada (llamando a WlanCloseHandle con el parámetro hClientHandle ) o si finaliza el proceso.

No llame a WlanRegisterNotification desde una función de devolución de llamada. Si el cliente está en medio de una devolución de llamada de notificación cuando se llama a WlanRegisterNotification con dwNotifSource establecido en WLAN_NOTIFICATION_SOURCE_NONE (es decir, cuando el cliente anula el registro de las notificaciones), WlanRegisterNotification esperará a que finalice la devolución de llamada antes de devolver un valor. Llamar a esta función dentro de una función de devolución de llamada dará como resultado que la llamada nunca se complete. Si tanto la función de devolución de llamada como el subproceso que anula el registro de las notificaciones intentan adquirir el mismo bloqueo, puede producirse un interbloqueo. Además, no llame a WlanRegisterNotification desde la función DllMain en un archivo DLL de aplicación. Esto también podría provocar un interbloqueo.

Una aplicación puede agotar el tiempo de espera y consultar el estado de la interfaz actual en lugar de esperar una notificación.

Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: El servicio Netman controla las notificaciones. Si el servicio Netman está deshabilitado o no está disponible, no se recibirán notificaciones. Si no se recibe una notificación dentro de un período de tiempo razonable, una aplicación debe agotar el tiempo de espera y consultar el estado de la interfaz actual.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista, Windows XP con SP3 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wlanapi.h (incluya Wlanapi.h)
Library	Wlanapi.lib
Archivo DLL	Wlanapi.dll
Redistribuible	API de LAN inalámbrica para Windows XP con SP2