WlanScan-Funktion (wlanapi.h)

Artikel
03/04/2024

Hinweis

Einige Informationen beziehen sich auf Vorabversionen, die vor der kommerziellen Freigabe grundlegend geändert werden können. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Wichtig

Diese API wird von bevorstehenden Änderungen am Betriebssystemverhalten beeinflusst, die für Herbst 2024 geplant sind. Weitere Informationen finden Sie unter Änderungen am API-Verhalten für Wi-Fi Zugriff und Speicherort.

Die WlanScan-Funktion fordert einen Scan nach verfügbaren Netzwerken auf der angegebenen Schnittstelle an.

Syntax

DWORD WlanScan(
  [in]           HANDLE               hClientHandle,
  [in]           const GUID           *pInterfaceGuid,
  [in, optional] const PDOT11_SSID    pDot11Ssid,
  [in, optional] const PWLAN_RAW_DATA pIeData,
                 PVOID                pReserved
);

Parameter

[in] hClientHandle

Das Sitzungshandle des Clients, das durch einen vorherigen Aufruf der WlanOpenHandle-Funktion abgerufen wurde.

[in] pInterfaceGuid

Die GUID der abzufragten Schnittstelle.

Die GUID jeder auf einem lokalen Computer aktivierten WLAN-Schnittstelle kann mithilfe der WlanEnumInterfaces-Funktion bestimmt werden.

[in, optional] pDot11Ssid

Ein Zeiger auf eine DOT11_SSID-Struktur , die die SSID des zu scannenden Netzwerks angibt. Dieser Parameter ist optional. Wenn sie auf NULL festgelegt ist, enthält die zurückgegebene Liste alle verfügbaren Netzwerke. Windows XP mit SP3 und WLAN-API für Windows XP mit SP2: Dieser Parameter muss NULL sein.

[in, optional] pIeData

Ein Zeiger auf ein Informationselement, das in Testanforderungen eingeschlossen werden soll. Dieser Parameter verweist auf eine WLAN_RAW_DATA-Struktur , die möglicherweise Informationen zur Clientbereitstellungsverfügbarkeit und 802.1X-Authentifizierungsanforderungen enthält. Windows XP mit SP3 und WLAN-API für Windows XP mit SP2: Dieser Parameter muss NULL sein.

pReserved

Für die zukünftige Verwendung reserviert. Muss auf NULL festgelegt werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Rückgabecodes sein.

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	hClientHandle ist NULL oder ungültig, pInterfaceGuid ist NULL oder pReserved ist nicht NULL.
ERROR_INVALID_HANDLE	Das Handle hClientHandle wurde in der Handle-Tabelle nicht gefunden.
RPC_STATUS	Verschiedene Fehlercodes.
ERROR_NOT_ENOUGH_MEMORY	Fehler beim Zuweisen von Arbeitsspeicher für die Abfrageergebnisse.

Hinweise

Die WlanScan-Funktion fordert an, dass der native 802.11-WLAN-Treiber nach verfügbaren Drahtlosnetzwerken sucht. Je nach Implementierung und den in den Parametern pDot11Ssid und pIeData übergebenen Werten sendet der Treiber möglicherweise Testanforderungen (aktive Überprüfung).

Wenn der pIeData-Parameter nicht NULL ist, sendet der Treiber während der Überprüfung Testanforderungen. Die Testanforderungen enthalten das Informationselement (IE), auf das der pIeData-Parameter verweist. Für instance kann der Wi-Fi Protected Setup (WPS) IE in die Testanforderungen einbezogen werden, um WPS-fähige Zugriffspunkte zu ermitteln. Der Puffer, auf den der pIeData-Parameter verweist, muss den vollständigen IE ab der Element-ID enthalten.

Der an die WlanScan-Funktion übergebene pIeData-Parameter kann einen Zeiger auf eine optionale WLAN_RAW_DATA-Struktur enthalten, die einen IE-Dateneintrag (Proximity Service Discovery, PSD) enthält.

Wenn sie zum Speichern eines PSD-IE verwendet wird, ist die in der Headerdatei "Wlanapi.h" definierte DOT11_PSD_IE_MAX_DATA_SIZE Konstante der Maximalwert des dwDataSize-Elements.

Konstante	Wert	BESCHREIBUNG
DOT11_PSD_IE_MAX_DATA_SIZE	240	Die maximale Datengröße eines PSD IE-Dateneintrags in Bytes.

Weitere Informationen zu PSD-IEs, einschließlich einer Diskussion über das Format eines PSD-IE, finden Sie in der WlanSetPsdIEDataList-Funktion .

Wenn die WlanScan-Funktion aufgerufen wird, kann der native 802.11-Wlan-Treiber die aktuelle Liste der verfügbaren Drahtlosnetzwerke löschen, bevor der Scan initiiert wird. Anwendungen sollten nicht davon ausgehen, dass der Aufruf der WlanScan-Funktion der vorhandenen Liste der verfügbaren drahtlosen Netzwerke hinzugefügt wird, die von den Funktionen WlanGetNetworkBssList oder WlanGetAvailableNetworkList aus vorherigen Scans zurückgegeben wurden.

Die WlanScan-Funktion wird sofort zurückgegeben. Um benachrichtigt zu werden, wenn die Netzwerküberprüfung abgeschlossen ist, muss sich ein Client unter Windows Vista und höher für Benachrichtigungen registrieren, indem Er WlanRegisterNotification aufruft. Für den dwNotifSource-Parameter , der an die WlanRegisterNotification-Funktion übergeben wird, muss das WLAN_NOTIFICATION_SOURCE_ACM Bit festgelegt sein, um sich für Benachrichtigungen zu registrieren, die vom Modul für die automatische Konfiguration generiert wurden. Drahtlose Netzwerktreiber, die die Windows-Logoanforderungen erfüllen, sind erforderlich, um eine WlanScan-Funktionsanforderung in 4 Sekunden abzuschließen.

Der Wlan-Dienst sendet keine Benachrichtigungen, wenn sich verfügbare Drahtlosnetzwerke ändern. Der Wlan-Dienst verfolgt keine Änderungen an der Liste der verfügbaren Netzwerke über mehrere Scans hinweg. Das aktuelle Standardverhalten besteht darin, dass der Wlan-LAN-Dienst den Treiber der Drahtlosen Schnittstelle nur alle 60 Sekunden aufsucht, und in einigen Fällen (wenn bereits eine Verbindung mit dem Drahtlosen Netzwerk hergestellt ist) der Wlan-Dienst überhaupt keine Überprüfungen anfragt. Die WlanScan-Funktion kann von einer Anwendung verwendet werden, um Änderungen im Drahtlosen Netzwerk nachzuverfolgen. Die Anwendung sollte sich zuerst für WLAN_NOTIFICATION_SOURCE_ACM Benachrichtigungen registrieren. Die WlanScan-Funktion kann dann aufgerufen werden, um einen Scan zu initiieren. Die Anwendung sollte dann warten, bis die wlan_notification_acm_scan_complete Benachrichtigung oder das Timeout nach 4 Sekunden empfangen wird. Anschließend kann die Anwendung die Funktion WlanGetNetworkBssList oder WlanGetAvailableNetworkList aufrufen, um eine Liste der verfügbaren drahtlosen Netzwerke abzurufen. Dieser Vorgang kann in regelmäßigen Abständen wiederholt werden, wobei die Anwendung Änderungen an verfügbaren drahtlosen Netzwerken nachverfolgt.

Die WlanScan-Funktion wird sofort zurückgegeben und stellt keine Benachrichtigung bereit, wenn der Scan unter Windows XP mit SP3 oder der Wlan-LAN-API für Windows XP mit SP2 abgeschlossen ist.

Da es für eine drahtlose Schnittstelle schwieriger wird, Datenpakete zu senden und zu empfangen, während ein Scan stattfindet, kann die WlanScan-Funktion die Latenz erhöhen, bis die Netzwerküberprüfung abgeschlossen ist.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista, Windows XP mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wlanapi.h (einschließlich Wlanapi.h)
Bibliothek	Wlanapi.lib
DLL	Wlanapi.dll
Verteilbare Komponente	Wlan-API für Windows XP mit SP2