Funzione WlanRegisterNotification (wlanapi.h)

Articolo
03/04/2024

Importante

Alcune informazioni si riferiscono a un prodotto di versione preliminare che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

La funzione WlanRegisterNotification viene usata per registrare e annullare la registrazione delle notifiche in tutte le interfacce wireless.

Sintassi

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
);

Parametri

[in] hClientHandle

Handle di sessione del client ottenuto da una chiamata precedente alla funzione WlanOpenHandle .

[in] dwNotifSource

Origini di notifica da registrare. Questi flag possono essere combinati. Quando questo parametro è impostato su WLAN_NOTIFICATION_SOURCE_NONE, WlanRegisterNotification annulla la registrazione delle notifiche in tutte le interfacce wireless.

I valori possibili per questo parametro sono definiti nei file di intestazione Wlanapi.h e L2cmn.h .

La tabella seguente mostra i valori possibili.

Valore	Significato
WLAN_NOTIFICATION_SOURCE_NONE	Annulla la registrazione delle notifiche.
WLAN_NOTIFICATION_SOURCE_ALL	Registra per tutte le notifiche disponibili nella versione del sistema operativo, incluse quelle generate dal modulo 802.1X. Per Windows XP con l'API LAN wireless sp3 per Windows XP con SP2, l'impostazione di dwNotifSource su WLAN_NOTIFICATION_SOURCE_ALL equivale a impostare dwNotifSource su WLAN_NOTIFICATION_SOURCE_ACM.
WLAN_NOTIFICATION_SOURCE_ACM	Registra per le notifiche generate dal modulo di configurazione automatica. Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Sono disponibili solo le notifiche di wlan_notification_acm_connection_complete e wlan_notification_acm_disconnected.
WLAN_NOTIFICATION_SOURCE_HNWK	Registra per le notifiche generate dalla rete ospitata wireless. Questa origine di notifica è disponibile in Windows 7 e in Windows Server 2008 R2 con il servizio LAN wireless installato.
WLAN_NOTIFICATION_SOURCE_ONEX	Registra per le notifiche generate da 802.1X.
WLAN_NOTIFICATION_SOURCE_MSM	Registra per le notifiche generate da MSM. Se il flag di WLAN_NOTIFICATION_SOURCE_MSM è impostato in dwNotifSource, è necessaria la funzionalità del dispositivo wiFiControl (vedere Dichiarazioni di funzionalità dell'app). Se tale funzionalità non viene concessa, la funzione restituisce ERROR_ACCESS_DENIED. La richiesta della funzionalità del dispositivo wiFiControl richiederà il consenso dell'utente per quanto riguarda l'accesso alla posizione. Per altre informazioni, vedere Modifiche al comportamento dell'API per Wi-Fi accesso e posizione. Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Questo valore non è supportato.
WLAN_NOTIFICATION_SOURCE_SECURITY	Registra per le notifiche generate dal modulo di sicurezza. Non sono attualmente definite notifiche per WLAN_NOTIFICATION_SOURCE_SECURITY. Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Questo valore non è supportato.
WLAN_NOTIFICATION_SOURCE_IHV	Registra per le notifiche generate dai fornitori hardware indipendenti (IHV). Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Questo valore non è supportato.
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	Registra per le notifiche generate dai servizi del dispositivo.

Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Questo parametro deve essere impostato su WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL o WLAN_NOTIFICATION_SOURCE_ACM.

[in] bIgnoreDuplicate

Specifica se le notifiche duplicate verranno ignorate. Se impostato su TRUE, una notifica non verrà inviata al client se è identica a quella precedente.

Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Questo parametro viene ignorato.

[in, optional] funcCallback

Tipo di WLAN_NOTIFICATION_CALLBACK che definisce il tipo di funzione di callback di notifica.

Questo parametro può essere NULL se il parametro dwNotifSource è impostato su WLAN_NOTIFICATION_SOURCE_NONE per annullare la registrazione delle notifiche in tutte le interfacce wireless,

[in, optional] pCallbackContext

Puntatore al contesto client che verrà passato alla funzione di callback con la notifica.

[in] pReserved

Riservato per utilizzi futuri. Deve essere impostato su NULL.

[out, optional] pdwPrevNotifSource

Puntatore alle origini di notifica registrate in precedenza.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici restituiti seguenti.

Se il flag di WLAN_NOTIFICATION_SOURCE_MSM è impostato in dwNotifSource, è necessaria la funzionalità del dispositivo wiFiControl (vedere Dichiarazioni di funzionalità dell'app). Se tale funzionalità non viene concessa, la funzione restituisce ERROR_ACCESS_DENIED. La richiesta della funzionalità del dispositivo wiFiControl richiederà il consenso dell'utente per quanto riguarda l'accesso alla posizione. Per altre informazioni, vedere Modifiche al comportamento dell'API per Wi-Fi accesso e posizione.

Codice restituito	Descrizione
ERROR_INVALID_PARAMETER	Un parametro non è corretto. Questo errore viene restituito se hClientHandle è NULL o non è valido o se pReserved non è NULL.
ERROR_INVALID_HANDLE	L'handle hClientHandle non è stato trovato nella tabella handle.
ERROR_NOT_ENOUGH_MEMORY	Impossibile allocare memoria per i risultati della query.
ERROR_ACCESS_DENIED	Se il flag WLAN_NOTIFICATION_SOURCE_MSM è impostato in dwNotifSource, è necessaria la funzionalità del dispositivo wiFiControl (vedere Dichiarazioni di funzionalità dell'app). Se tale funzionalità non viene concessa, la funzione restituisce ERROR_ACCESS_DENIED. La richiesta della funzionalità del dispositivo wiFiControl richiederà il consenso dell'utente per quanto riguarda l'accesso alla posizione. Per altre informazioni, vedere Modifiche al comportamento dell'API per Wi-Fi accesso e posizione.
RPC_STATUS	Vari codici di errore.

Commenti

WlanRegisterNotification viene usato da un'applicazione per registrare e annullare la registrazione delle notifiche in tutte le interfacce wireless. Durante la registrazione per le notifiche, un'applicazione deve fornire una funzione di callback a cui fa riferimento il parametro funcCallback . Il prototipo per questa funzione di callback è il WLAN_NOTIFICATION_CALLBACK. Questa funzione di callback riceverà notifiche registrate per nel parametro dwNotifSource passato alla funzione WlanRegisterNotification . La funzione di callback viene chiamata con un puntatore a una struttura WLAN_NOTIFICATION_DATA come primo parametro contenente informazioni dettagliate sulla notifica. La funzione di callback riceve anche un secondo parametro che contiene un puntatore al contesto client passato nel parametro pCallbackContext alla funzione WlanRegisterNotification .

La funzione WlanRegisterNotification restituirà un errore se dwNotifSource è un valore diverso da WLAN_NOTIFICATION_SOURCE_NONE e il client non fornisce una funzione di callback.

Una volta registrata, la funzione di callback verrà chiamata ogni volta che una notifica è disponibile fino a quando il client non esegue la registrazione o chiude l'handle.

Qualsiasi registrazione per ricevere notifiche causate da questa funzione verrà annullata automaticamente se l'applicazione chiamante chiude il relativo handle chiamante (chiamando WlanCloseHandle con il parametro hClientHandle ) o se il processo termina.

Non chiamare WlanRegisterNotification da una funzione di callback. Se il client si trova al centro di un callback di notifica quando WlanRegisterNotification viene chiamato con dwNotifSource impostato su WLAN_NOTIFICATION_SOURCE_NONE (ovvero quando il client non esegue la registrazione dalle notifiche), WlanRegisterNotification attenderà che il callback venga completato prima di restituire un valore. La chiamata a questa funzione all'interno di una funzione di callback comporterà il completamento della chiamata. Se sia la funzione di callback che il thread che annulla la registrazione dalle notifiche tentano di acquisire lo stesso blocco, può verificarsi un deadlock. Inoltre, non chiamare WlanRegisterNotification dalla funzione DllMain in una DLL dell'applicazione. Questo potrebbe anche causare un deadlock.

Un'applicazione può eseguire il timeout e eseguire query sullo stato dell'interfaccia corrente anziché attendere una notifica.

Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Le notifiche vengono gestite dal servizio Netman. Se il servizio Netman è disabilitato o non disponibile, le notifiche non verranno ricevute. Se una notifica non viene ricevuta entro un periodo di tempo ragionevole, un'applicazione deve eseguire il timeout e eseguire una query sullo stato dell'interfaccia corrente.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista, Windows XP con SP3 [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wlanapi.h (include Wlanapi.h)
Libreria	Wlanapi.lib
DLL	Wlanapi.dll
Componente ridistribuibile	API LAN wireless per Windows XP con SP2