WlanSetProfile-Funktion (wlanapi.h)

Artikel
12/22/2023

Die WlanSetProfile-Funktion legt den Inhalt eines bestimmten Profils fest.

Syntax

DWORD WlanSetProfile(
  [in]           HANDLE     hClientHandle,
  [in]           const GUID *pInterfaceGuid,
  [in]           DWORD      dwFlags,
  [in]           LPCWSTR    strProfileXml,
  [in, optional] LPCWSTR    strAllUserProfileSecurity,
  [in]           BOOL       bOverwrite,
  [in]           PVOID      pReserved,
  [out]          DWORD      *pdwReasonCode
);

Parameter

[in] hClientHandle

Das Sitzungshandle des Clients, das durch einen vorherigen Aufruf der WlanOpenHandle-Funktion abgerufen wurde.

[in] pInterfaceGuid

Die GUID der Schnittstelle.

[in] dwFlags

Die Flags, die für das Profil festgelegt werden sollen.

Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: dwFlags muss 0 sein. Benutzerspezifische Profile werden nicht unterstützt.

Wert	Bedeutung
0	Das Profil ist ein Benutzerprofil.
WLAN_PROFILE_GROUP_POLICY 0x00000001	Das Profil ist ein Gruppenrichtlinienprofil.
WLAN_PROFILE_USER 0x00000002	Das Profil ist ein Benutzerprofil.

[in] strProfileXml

Enthält die XML-Darstellung des Profils. Das WLANProfile-Element ist das Stammprofilelement. Beispielprofile finden Sie unter Beispiele für Drahtlosprofil. Es gibt keine vordefinierte maximale Zeichenfolgenlänge.

Windows XP mit SP3 und WLAN-API für Windows XP mit SP2: Das angegebene Profil muss die unter Kompatibilität des Drahtlosprofils beschriebenen Kompatibilitätskriterien erfüllen.

[in, optional] strAllUserProfileSecurity

Legt die Sicherheitsdeskriptorzeichenfolge für das All-User-Profil fest. Weitere Informationen zu Profilberechtigungen finden Sie im Abschnitt Hinweise.

Wenn dwFlags auf WLAN_PROFILE_USER festgelegt ist, wird dieser Parameter ignoriert.

Wenn dieser Parameter für ein neues Benutzerprofil auf NULL festgelegt ist, wird die Sicherheitsbeschreibung verwendet, die dem wlan_secure_add_new_all_user_profiles-Objekt zugeordnet ist. Wenn die Sicherheitsbeschreibung nicht durch einen WlanSetSecuritySettings-Aufruf geändert wurde, verfügen alle Benutzer über Standardberechtigungen für ein neues All-User-Profil. Rufen Sie WlanGetSecuritySettings auf , um die Standardberechtigungen abzurufen, die dem wlan_secure_add_new_all_user_profiles-Objekt zugeordnet sind.

Wenn dieser Parameter für ein vorhandenes Benutzerprofil auf NULL festgelegt ist, werden die Berechtigungen des Profils nicht geändert.

Wenn dieser Parameter für ein Benutzerprofil nicht NULL ist, wird die dem Profil zugeordnete Sicherheitsdeskriptorzeichenfolge erstellt oder geändert, nachdem das Sicherheitsdeskriptorobjekt erstellt und als Zeichenfolge analysiert wurde.

Windows XP mit SP3 und WLAN-API für Windows XP mit SP2: Dieser Parameter muss NULL sein.

[in] bOverwrite

Gibt an, ob dieses Profil ein vorhandenes Profil überschreibt. Wenn dieser Parameter FALSE ist und das Profil bereits vorhanden ist, wird das vorhandene Profil nicht überschrieben, und es wird ein Fehler zurückgegeben.

[in] pReserved

Für die zukünftige Verwendung reserviert. Muss auf NULL festgelegt werden.

[out] pdwReasonCode

Ein WLAN_REASON_CODE Wert, der angibt, warum das Profil ungültig 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
ERROR_ACCESS_DENIED	Der Aufrufer verfügt nicht über ausreichende Berechtigungen zum Festlegen des Profils. Wenn dwFlags auf 0 (d. h. beim Festlegen eines Benutzerprofils) aufgerufen wird, ruft WlanSetProfile die diskretionäre Zugriffssteuerungsliste (Discretionary Access Control List, DACL) ab, die mit dem wlan_secure_add_new_all_user_profiles-Objekt gespeichert ist. Wenn dwFlags auf WLAN_PROFILE_USER festgelegt ist , d. h. beim Festlegen eines Benutzerprofils, ruft WlanSetProfile die diskretionäre Zugriffssteuerungsliste (Discretionary Access Control List, DACL) ab, die mit dem wlan_secure_add_new_per_user_profiles-Objekt gespeichert ist. Wenn die DACL in beiden Fällen keinen Zugriffssteuerungseintrag (Access Control Entry, ACE) enthält, der WLAN_WRITE_ACCESS Berechtigung für das Zugriffstoken des aufrufenden Threads gewährt, gibt WlanSetProfileERROR_ACCESS_DENIED zurück.
ERROR_ALREADY_EXISTS	strProfileXml gibt ein bereits vorhandenes Netzwerk an. In der Regel wird dieser Rückgabewert verwendet, wenn bOverwritefalse ist. Wenn bOverwrite jedoch TRUE ist und dwFlags einen anderen Profiltyp als den vom vorhandenen Profil verwendeten angibt, wird das vorhandene Profil nicht überschrieben und ERROR_ALREADY_EXISTS zurückgegeben.
ERROR_BAD_PROFILE	Das von strProfileXml angegebene Profil ist ungültig. Wenn dieser Wert zurückgegeben wird, gibt pdwReasonCode den Grund an, warum das Profil ungültig ist.
ERROR_INVALID_PARAMETER	Eine der folgenden Bedingungen ist aufgetreten: hClientHandle ist NULL oder ungültig. pInterfaceGuid ist NULL. pReserved ist nicht NULL. strProfileXml ist NULL. [ConfigBlob] (/windows/desktop/eaphost/eaphostconfigschema-configblob-eaphostconfig-element). Wenn das Profil ein leeres ConfigBlob aufweisen muss, verwenden Sie `<ConfigBlob>00</ConfigBlob>` im Profil. pdwReasonCode ist NULL. dwFlags ist nicht auf einen der angegebenen Werte festgelegt. dwFlags ist auf WLAN_PROFILE_GROUP_POLICY und bOverwrite auf FALSE festgelegt.
ERROR_NO_MATCH	Die Schnittstelle unterstützt keine oder mehrere der im Profil angegebenen Funktionen. Wenn ein Profil beispielsweise die Verwendung von WPA2 angibt, wenn die NIC nur WPA unterstützt, wird dieser Fehlercode zurückgegeben. Wenn ein Profil die Verwendung des FIPS-Modus angibt, wenn die NIC den FIPS-Modus nicht unterstützt, wird dieser Fehlercode zurückgegeben.
RPC_STATUS	Verschiedene Fehlercodes.

Hinweise

Die WlanSetProfile-Funktion kann verwendet werden, um ein neues WLAN-Profil hinzuzufügen oder ein vorhandenes WLAN-Profil zu ersetzen.

Nach den Gruppenrichtlinienprofilen wird oben in der Liste ein neues Profil hinzugefügt. Die Position eines Profils in der Liste wird nicht geändert, wenn ein vorhandenes Profil überschrieben wird. Windows XP mit SP3 und WLAN-API für Windows XP mit SP2:

Ad-hoc-Profile werden nach den Infrastrukturprofilen in der Profilliste angezeigt. Wenn Sie ein neues Ad-hoc-Profil erstellen, wird es ganz oben in der Ad-hoc-Liste nach den Gruppenrichtlinien- und Infrastrukturprofilen platziert.

802.1X-Gastprofile, WPS-Profile (Wireless Provisioning Service) und Profile mit Wi-Fi Protected Access-None-Authentifizierung (WPA-None) werden nicht unterstützt. Das bedeutet, dass ein solches Profil nicht mit Native Wifi-Funktionen erstellt, gelöscht, aufgezählt oder zugegriffen werden kann. Jedes profil, das sich bereits in der Liste der bevorzugten Profile befindet, bleibt in der Liste, und seine Position in der Liste relativ zu anderen Profilen wird festgelegt, es sei denn, die Position der anderen Profile ändert sich.

Sie können WlanSetProfile für ein Profil aufrufen, das einen Klartextschlüssel enthält (also ein Profil mit dem geschützten Element vorhanden und auf FALSE festgelegt ist). Bevor das Profil im Profilspeicher gespeichert wird, wird das Schlüsselmaterial automatisch verschlüsselt. Wenn das Profil anschließend durch Aufrufen von WlanGetProfile aus dem Profilspeicher abgerufen wird, wird das verschlüsselte Schlüsselmaterial zurückgegeben. Windows XP mit SP3 und WLAN-API für Windows XP mit SP2: Das Schlüsselmaterial wird nie verschlüsselt.

Alle Benutzerprofile verfügen über drei zugeordnete Berechtigungen: Lesen, Schreiben und Ausführen. Wenn ein Benutzer über Lesezugriff verfügt, kann der Benutzer Profilberechtigungen anzeigen. Wenn ein Benutzer über Ausführungszugriff verfügt, verfügt der Benutzer über Lesezugriff, und der Benutzer kann mithilfe des Profils auch eine Verbindung mit einem Netzwerk herstellen und von diesem trennen. Wenn ein Benutzer Über Schreibzugriff verfügt, hat der Benutzer den Zugriff ausgeführt, und der Benutzer kann auch Berechtigungen ändern und löschen, die einem Profil zugeordnet sind.

Im Folgenden wird das Verfahren zum Erstellen eines Sicherheitsbeschreibungsobjekts und zum Analysieren als Zeichenfolge beschrieben.

Rufen Sie InitializeSecurityDescriptor auf, um einen Sicherheitsdeskriptor im Arbeitsspeicher zu erstellen.
Rufen Sie SetSecurityDescriptorOwner auf.
Rufen Sie InitializeAcl auf, um eine diskretionäre Zugriffssteuerungsliste (DACL) im Arbeitsspeicher zu erstellen.
Rufen Sie AddAccessAllowedAce oder AddAccessDeniedAce auf, um der DACL Zugriffssteuerungseinträge (ACEs) hinzuzufügen. Legen Sie den AccessMask-Parameter je nach Bedarf auf einen der folgenden Parameter fest:
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
Rufen Sie SetSecurityDescriptorDacl auf, um die DACL zum Sicherheitsdeskriptor hinzuzufügen.
Rufen Sie ConvertSecurityDescriptorToStringSecurityDescriptor auf, um den Deskriptor in Zeichenfolge zu konvertieren.

Die von ConvertSecurityDescriptorToStringSecurityDescriptor zurückgegebene Zeichenfolge kann dann beim Aufrufen von WlanSetProfile als strAllUserProfileSecurity-Parameterwert verwendet werden.

Für jedes wlan-Profil, das vom Native Wifi AutoConfig-Dienst verwendet wird, behält Windows das Konzept der benutzerdefinierten Benutzerdaten bei. Diese benutzerdefinierten Benutzerdaten sind zunächst nicht vorhanden, können aber durch Aufrufen der WlanSetProfileCustomUserData-Funktion festgelegt werden. Die benutzerdefinierten Benutzerdaten werden jedes Mal auf leer zurückgesetzt, wenn das Profil durch Aufrufen der WlanSetProfile-Funktion geändert wird. Nachdem benutzerdefinierte Benutzerdaten festgelegt wurden, kann mit der Funktion WlanGetProfileCustomUserData auf diese Daten zugegriffen werden.

Alle Drahtlos-LAN-Funktionen erfordern eine Schnittstellen-GUID für die Drahtlose Schnittstelle, wenn Profilvorgänge ausgeführt werden. Wenn eine drahtlose Schnittstelle entfernt wird, wird ihr Zustand aus WLANSVC (Wireless LAN Service) gelöscht, und es sind keine Profilvorgänge möglich.

Die WlanSetProfile-Funktion kann mit ERROR_INVALID_PARAMETER fehlschlagen, wenn die im pInterfaceGuid-Parameter angegebene Funkschnittstelle aus dem System entfernt wurde (z. B. ein usb-Funkadapter, der entfernt wurde).

Der Befehl netsh wlan add profile bietet ähnliche Funktionen an der Befehlszeile. Weitere Informationen finden Sie unter Netsh Commands for Wireless Local Area Network (WLAN).

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista, Windows XP mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wlanapi.h (einschließlich Wlanapi.h)
Bibliothek	Wlanapi.lib
DLL	Wlanapi.dll
Verteilbare Komponente	Wlan-API für Windows XP mit SP2