WlanHostedNetworkSetSecondaryKey-Funktion (wlanapi.h)

Artikel
08/28/2023

Die Funktion WlanHostedNetworkSetSecondaryKey konfiguriert den sekundären Sicherheitsschlüssel, der vom gehosteten Drahtlosnetzwerk verwendet wird.

Syntax

DWORD WlanHostedNetworkSetSecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [in]            DWORD                       dwKeyLength,
  [in]            PUCHAR                      pucKeyData,
  [in]            BOOL                        bIsPassPhrase,
  [in]            BOOL                        bPersistent,
  [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.

[in] dwKeyLength

Die Anzahl gültiger Datenbytes im Schlüsseldatenarray, auf das der pucKeyData-Parameter verweist. Diese Schlüssellänge sollte das endende "\0" enthalten, wenn es sich bei dem Schlüssel um eine Passphrase handelt.

[in] pucKeyData

Ein Zeiger auf einen Puffer, der die Schlüsseldaten enthält. Die Anzahl der gültigen Datenbytes im Puffer muss mindestens dem im dwKeyLength-Parameter angegebenen Wert entsprechen.

[in] bIsPassPhrase

Ein boolescher Wert, der angibt, ob das Schlüsseldatenarray, auf das der pucKeyData-Parameter verweist, im Passphraseformat vorliegt.

Wenn dieser Parameter TRUE ist, weist das Schlüsseldatenarray das Passphrasenformat auf. Wenn dieser Parameter FALSE ist, liegt das Schlüsseldatenarray nicht im Passphrasenformat vor.

[in] bPersistent

Ein boolescher Wert, der angibt, ob das Schlüsseldatenarray, auf das der pucKeyData-Parameter verweist, später gespeichert und wiederverwendet werden soll oder nur einmal verwendet werden soll.

Wenn dieser Parameter TRUE ist, soll das Schlüsseldatenarray gespeichert und später wiederverwendet werden. Wenn dieser Parameter FALSE ist, muss das Schlüsseldatenarray für eine Sitzung verwendet werden (entweder die aktuelle Sitzung oder die nächste Sitzung, wenn das gehostete Netzwerk nicht gestartet wird).

[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 vom 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 in der Handletabelle nicht gefunden wurde.
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn eine der folgenden Bedingungen auftritt: hClientHandle ist NULL. pucKeyData ist NULL. pucKeyData verweist nicht auf einen wohlgeformten gültigen Schlüssel. 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 drahtlose gehostete Netzwerk heruntergefahren wurde.
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 Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die WlanHostedNetworkSetSecondaryKey-Funktion ist eine Erweiterung für native Drahtlos-APIs, die zur Unterstützung des gehosteten Drahtlosnetzwerks unter Windows 7 und Windows Server 2008 R2 mit installiertem Wireless LAN-Dienst hinzugefügt wurde.

Eine Clientanwendung ruft die WlanHostedNetworkSetSecondaryKey-Funktion auf, um den sekundären Sicherheitsschlüssel zu konfigurieren, der vom gehosteten Drahtlosnetzwerk verwendet wird. Jede durch diese Funktion verursachte Änderung des gehosteten Netzwerks wird nicht automatisch rückgängig, wenn die aufrufende Anwendung ihr Aufrufhandle schließt (durch Aufrufen von WlanCloseHandle mit dem hClientHandle-Parameter ) oder wenn der Prozess beendet wird.

Nach dem Start ermöglicht das drahtlose gehostete Netzwerk drahtlosen Peers, diesen sekundären Sicherheitsschlüssel zusätzlich zum primären Sicherheitsschlüssel zuzuordnen. Der sekundäre Sicherheitsschlüssel wird immer nach Bedarf vom Benutzer angegeben, während der primäre Sicherheitsschlüssel vom Betriebssystem mit höherer Sicherheitsstärke generiert wird.

Der sekundäre Sicherheitsschlüssel, der im Puffer übergeben wird, auf den der Parameter pucKeyData verweist, wird mit WPA2-Personal Authentifizierung verwendet und sollte in einem der folgenden Formate vorliegen:

Eine Schlüsselpassphrase, die aus einem Array von ASCII-Zeichen von 8 bis 63 Zeichen besteht. Der dwKeyLength-Parameter sollte den abschlussenden "\0" in der Passphrase enthalten. Der Wert des dwKeyLength-Parameters sollte im Bereich von 9 bis 64 liegen.
Ein binärer Schlüssel, der aus 32 Bytes binärer Schlüsseldaten besteht. Der dwKeyLength-Parameter sollte für den binären Schlüssel 32 sein.

Um einen gültigen sekundären Sicherheitsschlüssel zu konfigurieren, sollte sich der dwKeyLength-Parameter im richtigen Bereich befinden, und der pucKeyData-Parameter sollte auf einen gültigen Speicherpuffer verweisen, der die angegebenen Datenbytes enthält. Um den derzeit konfigurierten sekundären Sicherheitsschlüssel aus dem System zu entfernen, sollte die Anwendung die WlanHostedNetworkSetSecondaryKey-Funktion mit null im dwKeyLength-Parameter und NULL im pucKeyData-Parameter aufrufen.

Die WlanHostedNetworkSetSecondaryKey-Funktion gibt ERROR_INVALID_PARAMETER zurück, wenn der pucKeyData-ParameterNULL ist, der dwKeyLength-Parameter jedoch nicht null ist. Die WlanHostedNetworkSetSecondaryKey-Funktion gibt auch ERROR_INVALID_PARAMETER zurück, wenn der dwKeyLength-Parameter null ist, der pucKeyData-Parameter jedoch nicht NULL ist.

Der sekundäre Sicherheitsschlüssel wird in der Regel festgelegt, bevor das drahtlose gehostete Netzwerk gestartet wird. Dann wird es verwendet, wenn das gehostete Netzwerk das nächste Mal gestartet wird.

Ein sekundärer Sicherheitsschlüssel kann auch festgelegt werden, nachdem das gehostete Netzwerk gestartet wurde. In diesem Fall wird der sekundäre Sicherheitsschlüssel sofort verwendet. Alle Clients, die den vorherigen sekundären Sicherheitsschlüssel verwenden, bleiben verbunden, können jedoch keine erneute Verbindung herstellen, wenn die Verbindung aus irgendeinem Grund getrennt wird oder das gehostete Drahtlosnetzwerk neu gestartet wird.

Der sekundäre Sicherheitsschlüssel kann als persistent angegeben werden, wenn der bPersistent-Parameter auf TRUE festgelegt ist. Wenn er als persistent angegeben wird, wird der sekundäre Sicherheitsschlüssel sofort verwendet, wenn das gehostete Netzwerk bereits gestartet ist, 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.

Jeder Benutzer kann diese Funktion aufrufen, um den sekundären Sicherheitsschlüssel für die Verwendung im gehosteten Netzwerk zu konfigurieren. 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 gehostetes 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 Drahtlosnetzwerkadapter 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 mit installiertem WLAN-Dienst verfügbar.

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 (wlanapi.h einschließen)
Bibliothek	Wlanapi.lib
DLL	Wlanapi.dll