Funzione WlanScan (wlanapi.h)
Nota
Alcune informazioni sono relative a un prodotto non definitivo, che potrebbe subire modifiche sostanziali prima del rilascio sul mercato. Microsoft non offre alcuna garanzia, esplicita o implicita, relativamente alle informazioni fornite.
Importante
Questa API sarà interessata dalle modifiche imminenti al comportamento del sistema operativo, previsto per l'autunno 2024. Per altre informazioni, vedere Modifiche al comportamento dell'API per Wi-Fi l'accesso e la posizione.
La funzione WlanScan richiede un'analisi delle reti disponibili nell'interfaccia indicata.
Sintassi
DWORD WlanScan(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in, optional] const PDOT11_SSID pDot11Ssid,
[in, optional] const PWLAN_RAW_DATA pIeData,
PVOID pReserved
);
Parametri
[in] hClientHandle
Handle di sessione del client, ottenuto da una chiamata precedente alla funzione WlanOpenHandle .
[in] pInterfaceGuid
GUID dell'interfaccia su cui eseguire query.
Il GUID di ogni interfaccia LAN wireless abilitata in un computer locale può essere determinato usando la funzione WlanEnumInterfaces .
[in, optional] pDot11Ssid
Puntatore a una struttura DOT11_SSID che specifica l'SSID della rete da analizzare. Questo parametro è facoltativo e, Se impostato su NULL, l'elenco restituito contiene tutte le reti disponibili. Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Questo parametro deve essere NULL.
[in, optional] pIeData
Puntatore a un elemento informativo da includere nelle richieste probe. Questo parametro punta a una struttura di WLAN_RAW_DATA che può includere informazioni sulla disponibilità del provisioning client e requisiti di autenticazione 802.1X. Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Questo parametro deve essere NULL.
pReserved
Riservato per utilizzi futuri. Deve essere impostato su NULL.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito può essere uno dei codici restituiti seguenti.
| Codice restituito | Descrizione |
|---|---|
|
hClientHandle è NULL o non valido, pInterfaceGuid è NULL o pReserved non è NULL. |
|
L'handle hClientHandle non è stato trovato nella tabella handle. |
|
Vari codici di errore. |
|
Impossibile allocare memoria per i risultati della query. |
Commenti
La funzione WlanScan richiede che il driver LAN wireless nativo 802.11 analizzi le reti wireless disponibili. Il driver può inviare o meno richieste probe (un'analisi attiva) a seconda dell'implementazione e dei valori passati nei parametri pDot11Ssid e pIeData .
Se il parametro pIeData non è NULL, il driver invierà richieste probe durante l'analisi. Le richieste probe includono l'elemento informativo (IE) a cui punta il parametro pIeData . Ad esempio, l'IE Wi-Fi Protected Setup (WPS) può essere incluso nelle richieste probe per individuare i punti di accesso che supportano WPS. Il buffer a cui punta il parametro pIeData deve contenere l'IE completo a partire dall'ID elemento.
Il parametro pIeData passato alla funzione WlanScan può contenere un puntatore a una struttura di WLAN_RAW_DATA facoltativa che contiene un'immissione dati di IE (Proximity Service Discovery).
Se usato per archiviare un IE PSD, la costante DOT11_PSD_IE_MAX_DATA_SIZE definita nel file di intestazione Wlanapi.h è il valore massimo del membro dwDataSize .
| Costante | Valore | Descrizione |
|---|---|---|
| DOT11_PSD_IE_MAX_DATA_SIZE | 240 | Dimensione massima dei dati, in byte, di una voce di dati di IE PSD. |
Per altre informazioni sugli IE PSD, inclusa una discussione sul formato di un IE PSD, vedere la funzione WlanSetPsdIEDataList .
Quando viene chiamata la funzione WlanScan , il driver LAN wireless nativo 802.11 può scaricare l'elenco corrente delle reti wireless disponibili prima dell'avvio dell'analisi. Le applicazioni non devono presupporre che la chiamata alla funzione WlanScan aggiunga all'elenco esistente di reti wireless disponibili restituite dalle funzioni WlanGetNetworkBssList o WlanGetAvailableNetworkList delle analisi precedenti.
La funzione WlanScan restituisce immediatamente. Per ricevere una notifica al termine dell'analisi di rete, un client in Windows Vista e versioni successive deve registrarsi per le notifiche chiamando WlanRegisterNotification. Il parametro dwNotifSource passato alla funzione WlanRegisterNotification deve avere il bit WLAN_NOTIFICATION_SOURCE_ACM impostato per la registrazione per le notifiche generate dal modulo di configurazione automatica. I driver di rete wireless che soddisfano i requisiti del logo di Windows sono necessari per completare una richiesta di funzione WlanScan in 4 secondi.
Il servizio LAN wireless non invia notifiche quando cambiano le reti wireless disponibili. Il servizio LAN wireless non tiene traccia delle modifiche apportate all'elenco delle reti disponibili tra più analisi. Il comportamento predefinito corrente è che il servizio LAN wireless chiede solo al driver dell'interfaccia wireless di cercare reti wireless ogni 60 secondi e in alcuni casi (quando già connesso alla rete wireless) il servizio LAN wireless non richiede alcuna analisi. La funzione WlanScan può essere utilizzata da un'applicazione per tenere traccia delle modifiche della rete wireless. L'applicazione deve prima registrarsi per le notifiche di WLAN_NOTIFICATION_SOURCE_ACM. La funzione WlanScan può quindi essere chiamata per avviare un'analisi. L'applicazione deve quindi attendere di ricevere la notifica wlan_notification_acm_scan_complete o il timeout dopo 4 secondi. L'applicazione può quindi chiamare la funzione WlanGetNetworkBssList o WlanGetAvailableNetworkList per recuperare un elenco di reti wireless disponibili. Questo processo può essere ripetuto periodicamente con l'applicazione che tiene traccia delle modifiche alle reti wireless disponibili.
La funzione WlanScan restituisce immediatamente e non fornisce una notifica quando l'analisi viene completata in Windows XP con SP3 o l'API LAN wireless per Windows XP con SP2.
Poiché diventa più difficile per un'interfaccia wireless inviare e ricevere pacchetti di dati mentre si verifica un'analisi, la funzione WlanScan può aumentare la latenza fino al completamento dell'analisi di rete.
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 |