WlanScan-Funktion (wlanapi.h)

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

Die Parameter

[in] hClientHandle

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

[in] pInterfaceGuid

Die GUID der schnittstelle, die abgefragt werden soll.

Die GUID jeder drahtlosen LAN-Schnittstelle, die auf einem lokalen Computer aktiviert ist, 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 kann NULL sein. Windows XP mit SP3 und Wireless LAN-API für Windows XP mit SP2: Dieser Parameter muss NULL sein.

[in, optional] pIeData

Ein Zeiger auf ein Informationselement, das in Probeanforderungen eingeschlossen werden soll. Dieser Parameter verweist auf eine WLAN_RAW_DATA Struktur, die Informationen zur Clientbereitstellungsverfügbarkeit und 802.1X-Authentifizierungsanforderungen enthalten kann. Windows XP mit SP3 und Wireless LAN-API für Windows XP mit SP2: Dieser Parameter muss NULL sein.

pReserved

Reserviert für zukünftige Verwendung. 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.

Bemerkungen

Die WlanScan-Funktion fordert an, dass der systemeigene 802.11 Wireless LAN-Treiber nach verfügbaren Drahtlosnetzwerken sucht. Je nach Implementierung und den in den Parametern pDot11Ssid und pIeData übergebenen Werten kann der Treiber Probeanforderungen (ein aktiver Scan) senden oder nicht.

Wenn der Parameter "pIeData " nicht NULL ist, sendet der Treiber Während des Scans Probeanforderungen. Die Prüfpunktanforderungen enthalten das Informationselement (IE), auf das der pIeData-Parameter verweist. Beispielsweise kann das Wi-Fi Protected Setup (WPS) IE in die Probeanforderungen aufgenommen werden, um WPS-fähige Zugriffspunkte zu ermitteln. Der Puffer, auf den der pIeData-Parameter verweist, muss den vollständigen IE enthalten, beginnend mit der Element-ID.

Der an die WlanScan-Funktion übergebene pIeData-Parameter kann einen Zeiger auf eine optionale WLAN_RAW_DATA Struktur enthalten, die eine Dateneingabe für den Näherungsdienst (Proximity Service Discovery, PSD) enthält.

Bei Verwendung zum Speichern eines PSD-IE ist die in der Headerdatei "Wlanapi.h" definierte DOT11_PSD_IE_MAX_DATA_SIZE Konstante der Maximalwert des dwDataSize-Elements.

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 systemeigene 802.11 Wireless LAN-Treiber die aktuelle Liste der verfügbaren Drahtlosnetzwerke leeren, bevor der Scan initiiert wird. Anwendungen sollten nicht davon ausgehen, dass durch aufrufen der WlanScan-Funktion die vorhandene Liste der verfügbaren Drahtlosnetzwerke hinzugefügt wird, die von den Funktionen WlanGetNetworkBssList oder WlanGetAvailableNetworkList aus vorherigen Scans zurückgegeben werden.

Die WlanScan-Funktion gibt sofort zurück. Um benachrichtigt zu werden, wenn der Netzwerkscan abgeschlossen ist, muss ein Client unter Windows Vista und höher durch Aufrufen von WlanRegisterNotification für Benachrichtigungen registriert werden. Der dwNotifSource-Parameter , der an die WlanRegisterNotification-Funktion übergeben wird, muss über das WLAN_NOTIFICATION_SOURCE_ACM Bit festgelegt sein, um Benachrichtigungen zu registrieren, die vom Modul für die automatische Konfiguration generiert werden. Wlan-Netzwerktreiber, die die Windows-Logo-Anforderungen erfüllen, müssen eine WlanScan-Funktionsanforderung in 4 Sekunden abschließen.

Der Wireless LAN-Dienst sendet keine Benachrichtigungen, wenn sich die verfügbaren Drahtlosnetzwerke ändern. Der Wireless LAN-Dienst verfolgt keine Änderungen an der Liste der verfügbaren Netzwerke über mehrere Scans hinweg. Das aktuelle Standardverhalten ist, dass der Wireless LAN-Dienst nur den Drahtlosschnittstellentreiber auffordern, alle 60 Sekunden nach Drahtlosnetzwerken zu suchen, und in einigen Fällen (wenn bereits mit dem Drahtlosnetzwerk verbunden) der Wireless LAN-Dienst überhaupt keine Überprüfungen anfragt. Die WlanScan-Funktion kann von einer Anwendung verwendet werden, um Änderungen des Drahtlosnetzwerks 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 nach 4 Sekunden warten, um die wlan_notification_acm_scan_complete Benachrichtigung oder das Timeout zu erhalten. Anschließend kann die Anwendung die WlanGetNetworkBssList - oder WlanGetAvailableNetworkList-Funktion aufrufen, um eine Liste der verfügbaren Drahtlosnetzwerke abzurufen. Dieser Vorgang kann regelmäßig wiederholt werden, wobei die Anwendung die Nachverfolgung von Änderungen an verfügbaren Drahtlosnetzwerken aufrecht erhält.

Die WlanScan-Funktion gibt sofort zurück und stellt keine Benachrichtigung bereit, wenn der Scan unter Windows XP mit SP3 oder der Wireless 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 auftritt, kann die WlanScan-Funktion die Latenz erhöhen, bis der Netzwerkscan abgeschlossen ist.

Anforderungen

Siehe auch

DOT11_SSID

WLAN_RAW_DATA

WlanEnumInterfaces

WlanGetAvailableNetworkList

WlanGetNetworkBssList

WlanRegisterNotification

WlanSetPsdIEDataList