WlanHostedNetworkSetProperty-Funktion (wlanapi.h)

Artikel
08/28/2023

Die WlanHostedNetworkSetProperty-Funktion legt statische Eigenschaften des drahtlosen gehosteten Netzwerks fest.

Syntax

DWORD WlanHostedNetworkSetProperty(
  [in]            HANDLE                      hClientHandle,
  [in]            WLAN_HOSTED_NETWORK_OPCODE  OpCode,
  [in]            DWORD                       dwDataSize,
  [in]            PVOID                       pvData,
  [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] OpCode

Der Bezeichner für die festzulegende Eigenschaft. Dieser Bezeichner kann nur die folgenden Werte in der WLAN_HOSTED_NETWORK_OPCODE Enumeration sein, die in der Headerdatei "Wlanapi.h " definiert ist:

wlan_hosted_network_opcode_connection_settings

Die Verbindungseinstellungen für gehostetes Netzwerk.

wlan_hosted_network_opcode_enable

Das Flag "Hosted Network enabled" (Gehostetes Netzwerk aktiviert).

[in] dwDataSize

Ein Wert, der die Größe des Puffers in Bytes angibt, auf den der pvData-Parameter verweist.

[in] pvData

Ein Zeiger auf einen Puffer, bei dem die statische Eigenschaft festgelegt werden soll. Der diesem Puffer zugeordnete Datentyp hängt vom Wert des OpCode-Parameters ab.

[out, optional] pFailReason

Ein optionaler Zeiger auf einen Wert, der den Fehlergrund empfängt, wenn der Aufruf der WlanHostedNetworkSetProperty-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. Dieser Fehler wird auch zurückgegeben, wenn der OpCode-Parameterwlan_hosted_network_opcode_enable wurde und das drahtlose gehostete Netzwerk per Gruppenrichtlinie für eine Domäne deaktiviert wurde.
ERROR_BAD_PROFILE	Das vom drahtlos gehosteten Netzwerk verwendete Netzwerkverbindungsprofil ist beschädigt.
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. OpCode gehört nicht zu den aufgezählten Werten, die im WLAN_HOSTED_NETWORK_OPCODE definiert sind. dwDataSize ist 0. pvData ist NULL. pvData verweist nicht auf eine wohlgeformte statische Eigenschaft. 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_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn die Anwendung die WlanHostedNetworkSetProperty-Funktion aufruft, wobei der OpCode-Parameter auf wlan_hosted_network_opcode_station_profile oder wlan_hosted_network_opcode_security_settings festgelegt 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 WlanHostedNetworkSetProperty-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-Dienst zu unterstützen.

Eine Clientanwendung ruft die WlanHostedNetworkSetProperty-Funktion auf, um die aktuellen statischen Eigenschaften des drahtlosen gehosteten Netzwerks festzulegen. Jede durch diese Funktion verursachte Änderung der Hosted Network-Eigenschaft wird nicht automatisch rückgängiggemacht, wenn die aufrufende Anwendung den aufrufenden Handle schließt (durch Aufrufen von WlanCloseHandle mit dem hClientHandle-Parameter ) oder wenn der Prozess beendet wird.

Der Datentyp, der dem Puffer zugeordnet ist, auf den der pvData-Parameter verweist, hängt wie folgt vom Wert des OpCode-Parameters ab:

OpCode	BESCHREIBUNG
wlan_hosted_network_opcode_connection_settings	Ein Zeiger auf eine WLAN_HOSTED_NETWORK_CONNECTION_SETTINGS-Struktur wird im pvData-Parameter übergeben.
wlan_hosted_network_opcode_enable	Im parameter pvData wird ein Zeiger auf BOOL übergeben.

Wenn die WlanHostedNetworkSetProperty-Funktion aufgerufen wird, wobei der OpCode-Parameter auf wlan_hosted_network_opcode_enable festgelegt ist, muss der Benutzer über die entsprechenden zugeordneten Berechtigungen verfügen. Berechtigungen werden in einer diskretionären Zugriffssteuerungsliste (DACL) gespeichert, die einem WLAN_SECURABLE_OBJECT zugeordnet ist. Um die WlanHostedNetworkSetProperty-Funktion mit dem OpCode-Parameter von wlan_hosted_network_opcode_enable 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

Wenn die WlanHostedNetworkSetProperty-Funktion einen der folgenden Werte im OpCode-Parameter übergeben wird, schlägt die Funktion mit ERROR_NOT_SUPPORTED fehl:

wlan_hosted_network_opcode_station_profile
wlan_hosted_network_opcode_connection_settings

Um erfolgreich zu sein, muss die WlanHostedNetworkSetProperty-Funktion die neuen Einstellungen beibehalten, was erfordert, dass der Zustand des gehosteten Netzwerks auf wlan_hosted_network_idle übergeht, wenn er gerade ausgeführt wurde (wlan_hosted_network_active).

Jeder Benutzer kann diese Funktion aufrufen, um die Eigenschaften des gehosteten Netzwerks festzulegen. Um das wlan_hosted_network_opcode_enable-Flag festzulegen, sind jedoch erhöhte Berechtigungen erforderlich. 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 "Netzwerkordner Connections" 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

Anforderung	Wert
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