WlanHostedNetworkQuerySecondaryKey-Funktion (wlanapi.h)

Artikel
08/28/2023

Die WlanHostedNetworkQuerySecondaryKey-Funktion fragt den sekundären Sicherheitsschlüssel ab, der für die Verwendung durch das drahtlose gehostete Netzwerk konfiguriert ist.

Syntax

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

Parameter

[in] hClientHandle

Das Sitzungshandle des Clients, das von einem vorherigen Aufruf der WlanOpenHandle-Funktion zurückgegeben wurde.

[out] pdwKeyLength

Ein Zeiger auf einen Wert, der die Anzahl gültiger Datenbytes im Schlüsseldatenarray angibt, auf das der parameter ppucKeyData verweist, wenn der Aufruf der WlanHostedNetworkQuerySecondaryKey-Funktion erfolgreich ist.

Diese Schlüssellänge schließt das beendende "\0" ein, wenn es sich bei dem Schlüssel um eine Passphrase handelt.

[out] ppucKeyData

Ein Zeiger auf einen Wert, der einen Zeiger auf den mit den sekundären Sicherheitsschlüsseldaten zurückgegebenen Puffer empfängt, wenn der Aufruf der WlanHostedNetworkQuerySecondaryKey-Funktion erfolgreich ist.

[out] pbIsPassPhrase

Ein Zeiger auf einen booleschen Wert, der angibt, ob das Schlüsseldatenarray, auf das vom parameter ppucKeyData verwiesen wird, im Passphrasenformat vorliegt.

Wenn dieser Parameter TRUE ist, befindet sich das Schlüsseldatenarray im Passphrasenformat. Wenn dieser Parameter FALSE ist, befindet sich das Schlüsseldatenarray nicht im Passphrasenformat.

[out] pbPersistent

Ein Zeiger auf einen booleschen Wert, der angibt, ob das Schlüsseldatenarray, auf das der parameter ppucKeyData verweist, später gespeichert und wiederverwendet werden soll oder nur für die einmalige Verwendung vorgesehen ist.

Wenn dieser Parameter TRUE ist, soll das Schlüsseldatenarray gespeichert und später wiederverwendet werden. Wenn dieser Parameter FALSE ist, ist das Schlüsseldatenarray nur zur einmaligen Verwendung vorgesehen.

[out, optional] pFailReason

Ein optionaler Zeiger auf einen Wert, der den Fehlergrund empfängt, wenn der Aufruf der WlanHostedNetworkSetSecondaryKey-Funktion fehlschlägt. Mögliche Werte für den Fehlergrund stammen aus dem WLAN_HOSTED_NETWORK_REASON Enumerationstyp, der in der Headerdatei "Wlanapi.h " definiert ist.

pvReserved

Für die zukünftige Verwendung reserviert. Dieser Parameter muss NULL sein.

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_HANDLE	Ein Handle ist ungültig. Dieser Fehler wird zurückgegeben, wenn das im hClientHandle-Parameter angegebene Handle nicht in der Handle-Tabelle gefunden wurde.
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn eine der folgenden Bedingungen auftritt: hClientHandle ist NULL. pdwKeyLength ist NULL. ppucKeyData ist NULL oder ungültig. pbIsPassPhrase ist NULL oder ungültig. pbPersistent ist NULL. pvReserved ist nicht NULL.
ERROR_INVALID_STATE	Die Ressource befindet sich nicht im richtigen Zustand, um den angeforderten Vorgang auszuführen. Dies kann auftreten, wenn das drahtlos gehostete Netzwerk während des Herunterfahrens war.
ERROR_OUTOFMEMORY	Für diesen Vorgang ist nicht genügend Speicher verfügbar.
ERROR_SERVICE_NOT_ACTIVE	Der Dienst wurde nicht gestartet. Dieser Fehler wird zurückgegeben, wenn der WLAN AutoConfig-Dienst nicht ausgeführt wird.
Andere	Verschiedene RPC- und andere Fehlercodes. Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die WlanHostedNetworkQuerySecondaryKey-Funktion ist eine Erweiterung für native drahtlose APIs, die hinzugefügt wurden, um das drahtlose gehostete Netzwerk unter Windows 7 und windows Server 2008 R2 mit installiertem Wlan-LAN-Dienst zu unterstützen.

Eine Clientanwendung ruft die WlanHostedNetworkQuerySecondaryKey-Funktion auf, um den sekundären Sicherheitsschlüssel abzufragen, der vom drahtlosen gehosteten Netzwerk verwendet wird. Diese Funktion gibt die Schlüsselinformationen zurück, einschließlich Schlüsseldaten, Schlüssellänge, ob es sich um eine Passphrase handelt und ob es sich um eine persistente oder einmalige Verwendung handelt. Diese Funktion ändert den Zustand oder die Eigenschaften des drahtlos gehosteten Netzwerks nicht.

Der sekundäre Sicherheitsschlüssel ist eine Passphrase, wenn der Wert, auf den der parameter pbIsPassPhrase verweist , TRUE ist. Der sekundäre Sicherheitsschlüssel ist ein binärer Schlüssel, wenn der Wert, auf den der parameter pbIsPassPhrase verweist, FALSE ist.

Der sekundäre Sicherheitsschlüssel, der im Puffer zurückgegeben wird, auf den der Parameter ppucKeyData verweist, wird mit WPA2-Personal Authentifizierung verwendet und hat eines der folgenden Formate:

Eine Schlüsselpassphrase, die aus einem Array von ASCII-Zeichen zwischen 8 und 63 Zeichen besteht. Der Wert, auf den der parameter pdwKeyLength verweist, enthält das beendende "\0" in der Passphrase. Der Wert, auf den der pdwKeyLength-Parameter verweist, sollte im Bereich von 9 bis 64 liegen.
Ein binärer Schlüssel, der aus 32 Bytes binärer Schlüsseldaten besteht. Der Wert, auf den der parameter pdwKeyLength verweist, sollte für den Binärschlüssel 32 sein.

Der sekundäre Sicherheitsschlüssel ist persistent, wenn der Wert, auf den der parameter pbPersistent verweist, TRUE ist. Wenn der sekundäre Sicherheitsschlüssel dauerhaft ist, wird er sofort verwendet, wenn das gehostete Netzwerk bereits gestartet wurde, und auch wiederverwendet, wenn das gehostete Netzwerk in Zukunft gestartet wird.

Wenn der sekundäre Sicherheitsschlüssel nicht als persistent angegeben ist, wird er sofort verwendet, wenn das gehostete Netzwerk bereits gestartet wurde, oder nur für das nächste Mal, wenn das gehostete Netzwerk gestartet wird. Nachdem das gehostete Netzwerk beendet wurde, wird dieser sekundäre Sicherheitsschlüssel nie wieder verwendet und aus dem System entfernt.

Wenn derzeit kein sekundärer Sicherheitsschlüssel konfiguriert ist, ist der zurückgegebene Wert, auf den der parameter pdwKeyLength verweist, null, und der im ppucKeyData-Parameter zurückgegebene Wert ist NULL. In diesem Fall ist der wert, der in den Parametern pbIsPassPhrase und pbPersistent zurückgegeben wird, bedeutungslos .

Wenn die WlanHostedNetworkQuerySecondaryKey-Funktion erfolgreich ist, sollte der speicher, der für den Puffer im zurückgegebenen ppucKeyData-Parameter verwendet wird, nach der Verwendung durch Aufrufen der WlanFreeMemory-Funktion freigegeben werden.

Jeder Benutzer kann die WlanHostedNetworkQuerySecondaryKey-Funktion aufrufen, um den sekundären Sicherheitsschlüssel abzufragen, der im gehosteten Netzwerk verwendet wird. Die Möglichkeit, das drahtlos gehostete Netzwerk zu aktivieren, kann jedoch durch Gruppenrichtlinien in einer Domäne eingeschränkt werden.

Unter Windows 7 und höher installiert das Betriebssystem ein virtuelles Gerät, wenn auf dem Computer ein gehosteter netzwerkfähiger Drahtlosadapter vorhanden ist. Dieses virtuelle Gerät wird normalerweise im Ordner "Netzwerkverbindungen" als "Drahtlose Netzwerkverbindung 2" mit dem Gerätenamen "Microsoft Virtual WiFi Miniport-Adapter" angezeigt, wenn der Computer über einen einzelnen Drahtlosen Netzwerkadapter verfügt. Dieses virtuelle Gerät wird ausschließlich zum Ausführen von SoftAP-Verbindungen (Software Access Point) verwendet und ist nicht in der Liste enthalten, die von der WlanEnumInterfaces-Funktion zurückgegeben wird. Die Lebensdauer dieses virtuellen Geräts ist an den physischen Drahtlosadapter gebunden. Wenn der physische Drahtlosadapter deaktiviert ist, wird auch dieses virtuelle Gerät entfernt. Dieses Feature ist auch unter Windows Server 2008 R2 verfügbar, wobei der Wireless LAN-Dienst installiert ist.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wlanapi.h (einschließlich Wlanapi.h)
Bibliothek	Wlanapi.lib
DLL	Wlanapi.dll