WlanGetNetworkBssList-Funktion (wlanapi.h)
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 WlanGetNetworkBssList-Funktion ruft eine Liste der BSS-Einträge (Basic Service Set) des Drahtlosnetzwerks oder der Netzwerke auf einer bestimmten WLAN-Schnittstelle ab.
Syntax
DWORD WlanGetNetworkBssList(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[optional] const PDOT11_SSID pDot11Ssid,
[in] DOT11_BSS_TYPE dot11BssType,
[in] BOOL bSecurityEnabled,
PVOID pReserved,
[out] PWLAN_BSS_LIST *ppWlanBssList
);
Parameter
[in] hClientHandle
Das Sitzungshandle des Clients, das durch einen vorherigen Aufruf der WlanOpenHandle-Funktion abgerufen wurde.
[in] pInterfaceGuid
Ein Zeiger auf die GUID der abzufragten WLAN-Schnittstelle.
Die GUID jeder auf einem lokalen Computer aktivierten WLAN-Schnittstelle kann mithilfe der WlanEnumInterfaces-Funktion ermittelt werden.
[optional] pDot11Ssid
Ein Zeiger auf eine DOT11_SSID-Struktur , die die SSID des Netzwerks angibt, von dem die BSS-Liste angefordert wird. Dieser Parameter ist optional. Bei Festlegung auf NULL enthält die zurückgegebene Liste alle verfügbaren BSS-Einträge auf einer WLAN-Schnittstelle.
Wenn ein Zeiger auf eine DOT11_SSID-Struktur angegeben wird, muss die SSID-Länge, die im uSSIDLength-Element der DOT11_SSID-Struktur angegeben ist, kleiner oder gleich DOT11_SSID_MAX_LENGTH sein, die in der Headerdatei "Wlantypes.h " definiert ist. Darüber hinaus muss der parameter dot11BssType entweder auf dot11_BSS_type_infrastructure oder dot11_BSS_type_independent und der bSecurityEnabled-Parameter angegeben werden.
[in] dot11BssType
Der BSS-Typ des Netzwerks. Dieser Parameter wird ignoriert, wenn die SSID des Netzwerks für die BSS-Liste nicht angegeben ist (der Parameter pDot11Ssid ist NULL).
Dieser Parameter kann einer der folgenden Werte sein, die in der DOT11_BSS_TYPE-Enumeration definiert sind, die in der Wlantypes.h-Headerdatei definiert ist.
[in] bSecurityEnabled
Ein -Wert, der angibt, ob die Sicherheit im Netzwerk aktiviert ist. Dieser Parameter ist nur gültig, wenn die SSID des Netzwerks für die BSS-Liste angegeben ist (der Parameter pDot11Ssid ist nicht NULL).
pReserved
Für die zukünftige Verwendung reserviert. Dieser Parameter muss auf NULL festgelegt werden.
[out] ppWlanBssList
Ein Zeiger auf den Speicher für einen Zeiger, um die zurückgegebene Liste der BSS-Einträge in einer WLAN_BSS_LIST-Struktur zu empfangen.
Der Puffer für die zurückgegebene WLAN_BSS_LIST wird von der WlanGetNetworkBssList-Funktion zugeordnet, wenn der Aufruf erfolgreich ist.
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 |
|---|---|
|
Das Handle hClientHandle wurde in der Handletabelle nicht gefunden. |
|
Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn der Parameter hClientHandle, pInterfaceGuid oder ppWlanBssListNULL ist. Dieser Fehler wird zurückgegeben, wenn pReserved nicht NULL ist. Dieser Fehler wird auch zurückgegeben, wenn hClientHandle, die im pDot11Ssid-Parameter angegebene SSID oder der im dot11BssType-Parameter angegebene BSS-Typ ungültig ist. |
|
Das der Schnittstelle zugeordnete Funkgerät ist deaktiviert. Die BSS-Liste ist nicht verfügbar, wenn das Funkgerät ausgeschaltet ist. |
|
Es ist nicht genügend Arbeitsspeicher verfügbar, um diese Anforderung zu verarbeiten und Arbeitsspeicher für die Abfrageergebnisse zuzuweisen. |
|
Das Element wurde nicht gefunden. Dieser Fehler wird zurückgegeben, wenn die im pInterfaceGuid-Parameter angegebene GUID der abzufragenden Schnittstelle nicht gefunden werden konnte. |
|
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn diese Funktion von einem Windows XP mit SP3 oder einer Wlan-LAN-API für Windows XP mit SP2-Client aufgerufen wurde. Dieser Fehler wird auch zurückgegeben, wenn der WLAN AutoConfig-Dienst deaktiviert ist. |
|
Der WLAN AutoConfig-Dienst wurde nicht gestartet. |
|
Verschiedene Fehlercodes. |
Hinweise
Die WlanGetNetworkBssList-Funktion ruft die Standard-Dienstsatzliste für jedes Drahtlosnetzwerk oder jedes Drahtlosnetzwerk ab, auf das über eine bestimmte Schnittstelle zugegriffen werden kann. Die Liste der für jedes Drahtlosnetzwerk zurückgegebenen Informationen enthält auch eine Liste der Informationselemente, die von jedem Zugriffspunkt für ein BSS-Infrastrukturnetzwerk oder einen Netzwerkpeer für ein unabhängiges BSS-Netzwerk (Ad-hoc-Netzwerk) zurückgegeben werden. Die Informationen werden als Zeiger auf eine WLAN_BSS_LIST-Struktur im ppWlanBssList-Parameter zurückgegeben. Die WLAN_BSS_LIST-Struktur enthält eine Elementanzahl gefolgt von einem Array von WLAN_BSS_ENTRY Struktureinträgen.
Da die von der WlanGetNetworkBssList-Funktion zurückgegebenen Informationen von einem Zugriffspunkt für ein BSS-Infrastrukturnetzwerk oder von einem Netzwerkpeer für ein unabhängiges BSS-Netzwerk (Ad-hoc-Netzwerk) gesendet werden, sollten die zurückgegebenen Informationen nicht vertrauenswürdig sein. Die Elemente ulIeOffset und ulIeSize in der WLAN_BSS_ENTRY-Struktur sollten verwendet werden, um die Größe des Datenblobs des Informationselements in der WLAN_BSS_ENTRY-Struktur zu bestimmen, nicht die Daten im Datenblob des Informationselements selbst. Die WlanGetNetworkBssList-Funktion überprüft nicht, ob alle Informationen, die im Datenblob des Informationselements zurückgegeben werden, auf das vom ulIeOffset-Member verwiesen wird, ein gültiges Informationselement sind, wie in den IEEE 802.11-Standards für drahtlose LANs definiert.
Wenn der pDot11Ssid-Parameter angegeben ist (nicht NULL), muss der angegebene dot11BssType-Parameter entweder auf dot11_BSS_type_infrastructure für ein BSS-Infrastrukturnetzwerk oder dot11_BSS_type_independent für ein unabhängiges BSS-Netzwerk (Ad-hoc-Netzwerk) festgelegt werden. Wenn der parameter dot11BssType auf dot11_BSS_type_any festgelegt ist, gibt die WlanGetNetworkBssList-Funktion ERROR_SUCCESS aber es werden keine BSS-Einträge zurückgegeben.
Um eine Liste aller BSS-Infrastrukturnetzwerke und unabhängigen BSS-Netzwerke (Ad-hoc-Netzwerke) auf einer Wlan-Schnittstelle zurückzugeben, legen Sie den Parameter pDot11Ssid auf NULL fest. Wenn die Wlan-Schnittstelle auch als drahtlos gehostetes Netzwerk ausgeführt wird, enthält die BSS-Liste einen Eintrag für die BSS, die für das drahtlos gehostete Netzwerk erstellt wurde.
Die WlanGetNetworkBssList-Funktion gibt ERROR_SUCCESS zurück, wenn eine leere BSS-Liste vom WLAN AutoConfig-Dienst zurückgegeben wird. Eine Anwendung, die die WlanGetNetworkBssList-Funktion aufruft, muss vor dem Zugriff auf das element wlanBssEntries[0] in WLAN_BSS_LIST Struktur überprüfen, ob der dwNumberOfItems-Member des WLAN_BSS_LIST, auf den der ppWlanBssList-Parameter verweist, nicht null ist.
Die WlanGetNetworkBssList-Funktion ordnet Arbeitsspeicher für die Standarddienstsatzliste zu, die in einem Puffer zurückgegeben wird, auf den der ppWlanBssList-Parameter verweist, wenn die Funktion erfolgreich ist. Der für den Puffer verwendete Arbeitsspeicher, auf den der ppWlanBssList-Parameter verweist, sollte durch Aufrufen der WlanFreeMemory-Funktion freigegeben werden, nachdem der Puffer nicht mehr benötigt wird.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wlanapi.h (wlanapi.h einschließen) |
| Bibliothek | Wlanapi.lib |
| DLL | Wlanapi.dll |