WlanHostedNetworkForceStart-Funktion (wlanapi.h)

Artikel
08/28/2023

Die WlanHostedNetworkForceStart-Funktion übergibt das drahtlos gehostete Netzwerk in den wlan_hosted_network_active Zustand , ohne dass die Anforderung dem Aufrufhandle der Anwendung zugeordnet wird.

Syntax

DWORD WlanHostedNetworkForceStart(
  [in]            HANDLE                      hClientHandle,
  [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, optional] pFailReason

Ein optionaler Zeiger auf einen Wert, der den Fehlergrund empfängt, wenn der Aufruf der WlanHostedNetworkForceStart-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_ACCESS_DENIED	Der Aufrufer verfügt nicht über ausreichende Berechtigungen.
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. pvReserved ist nicht NULL.
ERROR_INVALID_STATE	Die Ressource befindet sich nicht im richtigen Zustand, um den angeforderten Vorgang auszuführen. Dieser Fehler wird zurückgegeben, wenn das drahtlos gehostete Netzwerk durch eine Gruppenrichtlinie für eine Domäne deaktiviert ist.
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 WlanHostedNetworkForceStart-Funktion ist eine Erweiterung für native Drahtlos-APIs, die hinzugefügt wurden, um das drahtlose gehostete Netzwerk unter Windows 7 und windows Server 2008 R2 mit installiertem WLAN-Dienst zu unterstützen.

Eine Clientanwendung ruft die WlanHostedNetworkForceStart-Funktion auf, um den Start des drahtlosen gehosteten Netzwerks zu erzwingen, indem das drahtlose gehostete Netzwerk in den wlan_hosted_network_active Zustand übergeht, ohne die Anforderung dem Aufrufhandle der Anwendung zuzuordnen. Ein erfolgreicher Aufruf der WlanHostedNetworkForceStart-Funktion sollte schließlich durch einen Aufruf der WlanHostedNetworkForceStop-Funktion abgeglichen werden. Jede durch diese Funktion verursachte Änderung des Hosted Network-Zustands wird nicht automatisch rückgängiggemacht, wenn die aufrufende Anwendung ihr aufrufende Handle schließt (durch Aufrufen von WlanCloseHandle mit dem hClientHandle-Parameter ) oder wenn der Prozess beendet wird.

Die Kosten für den Aufruf der WlanHostedNetworkForceStart-Funktion gegenüber dem Aufrufen von WlanHostedNetworkStartUsing sind die zugeordneten erforderlichen Berechtigungen. Eine Anwendung kann die WlanHostedNetworkForceStart-Funktion aufrufen, nachdem sichergestellt wurde, dass ein Systembenutzer mit erhöhten Kräften die erhöhten Energieanforderungen akzeptiert, die mit der Ausführung des gehosteten drahtlosen Netzwerks für längere Zeit verbunden sind.

Die WlanHostedNetworkForceStart-Funktion kann fehlschlagen, wenn der Zustand des gehosteten Netzwerks wlan_hosted_network_unavailable ist oder der Aufrufer nicht über ausreichende Berechtigungen verfügt.

Diese Funktion, um den Start des gehosteten Netzwerks zu erzwingen, kann nur aufgerufen werden, wenn der Benutzer über die entsprechenden zugeordneten Berechtigungen verfügt. Berechtigungen werden in einer diskretionären Zugriffssteuerungsliste (DACL) gespeichert, die einem WLAN_SECURABLE_OBJECT zugeordnet ist. Um wlanHostedNetworkForceStart aufzurufen, muss das Clientzugriffstoken des Aufrufers über erhöhte Berechtigungen verfügen, die durch die folgende Enumeration in WLAN_SECURABLE_OBJECT verfügbar gemacht werden:

wlan_secure_hosted_network_elevated_access

Die Möglichkeit, das drahtlos gehostete Netzwerk zu aktivieren, kann auch 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