Fungsi WlanSetProfile (wlanapi.h)

Artikel
03/15/2023

Fungsi WlanSetProfile mengatur konten profil tertentu.

Sintaks

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

Handel sesi klien, diperoleh dari panggilan sebelumnya ke fungsi WlanOpenHandle .

[in] pInterfaceGuid

GUID antarmuka.

[in] dwFlags

Bendera yang akan diatur pada profil.

Windows XP dengan SP3 dan Wireless LAN API untuk Windows XP dengan SP2: dwFlags harus 0. Profil per pengguna tidak didukung.

Nilai	Makna
0	Profil adalah profil semua pengguna.
WLAN_PROFILE_GROUP_POLICY 0x00000001	Profil adalah profil kebijakan grup.
WLAN_PROFILE_USER 0x00000002	Profil adalah profil per pengguna.

[in] strProfileXml

Berisi representasi XML profil. Elemen WLANProfile adalah elemen profil akar. Untuk melihat contoh profil, lihat Sampel Profil Nirkabel. Tidak ada panjang string maksimum yang telah ditentukan sebelumnya.

Windows XP dengan SP3 dan Wireless LAN API untuk Windows XP dengan SP2: Profil yang disediakan harus memenuhi kriteria kompatibilitas yang dijelaskan dalam Kompatibilitas Profil Nirkabel.

[in, optional] strAllUserProfileSecurity

Mengatur string deskriptor keamanan pada profil semua pengguna. Untuk informasi selengkapnya tentang izin profil, lihat bagian Keterangan.

Jika dwFlags diatur ke WLAN_PROFILE_USER, parameter ini diabaikan.

Jika parameter ini diatur ke NULL untuk profil semua pengguna baru, deskriptor keamanan yang terkait dengan objek wlan_secure_add_new_all_user_profiles digunakan. Jika deskriptor keamanan belum dimodifikasi oleh panggilan WlanSetSecuritySettings , semua pengguna memiliki izin default pada profil semua pengguna baru. Panggil WlanGetSecuritySettings untuk mendapatkan izin default yang terkait dengan objek wlan_secure_add_new_all_user_profiles.

Jika parameter ini diatur ke NULL untuk profil semua pengguna yang ada, izin profil tidak diubah.

Jika parameter ini bukan NULL untuk profil semua pengguna, string deskriptor keamanan yang terkait dengan profil dibuat atau dimodifikasi setelah objek deskriptor keamanan dibuat dan diurai sebagai string.

Windows XP dengan SP3 dan Wireless LAN API untuk Windows XP dengan SP2: Parameter ini harus NULL.

[in] bOverwrite

Menentukan apakah profil ini menimpa profil yang ada. Jika parameter ini FALSE dan profil sudah ada, profil yang ada tidak akan ditimpa dan kesalahan akan dikembalikan.

[in] pReserved

Disiapkan untuk penggunaan masa mendatang. Harus diatur ke NULL.

[out] pdwReasonCode

Nilai WLAN_REASON_CODE yang menunjukkan mengapa profil tidak valid.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan mungkin merupakan salah satu kode pengembalian berikut.

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Pemanggil tidak memiliki izin yang memadai untuk mengatur profil. Ketika dipanggil dengan dwFlags diatur ke 0 - yaitu, saat mengatur profil semua pengguna - WlanSetProfile mengambil daftar kontrol akses diskresi (DACL) yang disimpan dengan objek wlan_secure_add_new_all_user_profiles . Ketika dipanggil dengan dwFlags diatur ke WLAN_PROFILE_USER - yaitu, saat mengatur profil per pengguna - WlanSetProfile mengambil daftar kontrol akses diskresi (DACL) yang disimpan dengan objek wlan_secure_add_new_per_user_profiles . Dalam kedua kasus, jika DACL tidak berisi entri kontrol akses (ACE) yang memberikan izin WLAN_WRITE_ACCESS ke token akses utas panggilan, maka WlanSetProfile mengembalikan ERROR_ACCESS_DENIED.
ERROR_ALREADY_EXISTS	strProfileXml menentukan jaringan yang sudah ada. Biasanya, nilai pengembalian ini digunakan ketika bOverwrite adalah FALSE; namun, jika bOverwrite adalah TRUE dan dwFlags menentukan jenis profil yang berbeda dari yang digunakan oleh profil yang ada, profil yang ada tidak akan ditimpa dan ERROR_ALREADY_EXISTS akan dikembalikan.
ERROR_BAD_PROFILE	Profil yang ditentukan oleh strProfileXml tidak valid. Jika nilai ini dikembalikan, pdwReasonCode menentukan alasan profil tidak valid.
ERROR_INVALID_PARAMETER	Salah satu kondisi berikut terjadi: hClientHandleadalah NULL atau tidak valid. pInterfaceGuid adalah NULL. pReserved bukan NULL. strProfileXml adalah NULL. [ConfigBlob] (/windows/desktop/eaphost/eaphostconfigschema-configblob-eaphostconfig-element). Jika profil harus memiliki ConfigBlob kosong, gunakan `<ConfigBlob>00</ConfigBlob>` di profil. pdwReasonCode adalah NULL. dwFlags tidak diatur ke salah satu nilai yang ditentukan. dwFlags diatur ke WLAN_PROFILE_GROUP_POLICY dan bOverwrite diatur ke FALSE.
ERROR_NO_MATCH	Antarmuka tidak mendukung satu atau beberapa kemampuan yang ditentukan dalam profil. Misalnya, jika profil menentukan penggunaan WPA2 ketika NIC hanya mendukung WPA, maka kode kesalahan ini dikembalikan. Selain itu, jika profil menentukan penggunaan mode FIPS ketika NIC tidak mendukung mode FIPS, maka kode kesalahan ini dikembalikan.
RPC_STATUS	Berbagai kode kesalahan.

Keterangan

Fungsi WlanSetProfile dapat digunakan untuk menambahkan profil LAN nirkabel baru atau mengganti profil LAN nirkabel yang ada.

Profil baru ditambahkan di bagian atas daftar setelah profil kebijakan grup. Posisi profil dalam daftar tidak diubah jika profil yang ada ditimpa. Windows XP dengan SP3 dan Wireless LAN API untuk Windows XP dengan SP2:

Profil ad hoc muncul setelah profil infrastruktur di daftar profil. Jika Anda membuat profil ad hoc baru, profil tersebut ditempatkan di bagian atas daftar ad hoc, setelah kebijakan grup dan profil infrastruktur.

Profil tamu 802.1X, profil Wireless Provisioning Service (WPS), dan profil dengan autentikasi Wi-Fi Protected Access-None (WPA-None) tidak didukung. Itu berarti profil seperti itu tidak dapat dibuat, dihapus, dijumlahkan, atau diakses menggunakan fungsi Wifi Asli. Profil apa pun yang sudah ada dalam daftar profil pilihan akan tetap ada dalam daftar, dan posisinya dalam daftar relatif terhadap profil lain diperbaiki kecuali posisi profil lain berubah.

Anda dapat memanggil WlanSetProfile pada profil yang berisi kunci teks biasa (yaitu, profil dengan elemen terproteksi yang ada dan diatur ke FALSE). Sebelum profil disimpan di penyimpanan profil, materi kunci dienkripsi secara otomatis. Ketika profil kemudian diambil dari penyimpanan profil dengan memanggil WlanGetProfile, materi kunci terenkripsi dikembalikan. Windows XP dengan SP3 dan Wireless LAN API untuk Windows XP dengan SP2: Materi kunci tidak pernah dienkripsi.

Profil semua pengguna memiliki tiga izin terkait: baca, tulis, dan jalankan. Jika pengguna memiliki akses baca, pengguna dapat melihat izin profil. Jika pengguna telah menjalankan akses, pengguna memiliki akses baca dan pengguna juga dapat terhubung dan memutuskan sambungan dari jaringan menggunakan profil. Jika pengguna memiliki akses tulis, pengguna telah menjalankan akses dan pengguna juga dapat mengubah dan menghapus izin yang terkait dengan profil.

Berikut ini menjelaskan prosedur untuk membuat objek deskriptor keamanan dan mengurainya sebagai string.

Panggil InitializeSecurityDescriptor untuk membuat deskriptor keamanan dalam memori.
Panggil SetSecurityDescriptorOwner.
Panggil InitializeAcl untuk membuat daftar kontrol akses diskresi (DACL) dalam memori.
Panggil AddAccessAllowedAce atau AddAccessDeniedAce untuk menambahkan entri kontrol akses (ACE) ke DACL. Atur parameter AccessMask ke salah satu hal berikut ini yang sesuai:
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
Panggil SetSecurityDescriptorDacl untuk menambahkan DACL ke deskriptor keamanan.
Panggil ConvertSecurityDescriptorToStringSecurityDescriptor untuk mengonversi deskriptor menjadi string.

String yang dikembalikan oleh ConvertSecurityDescriptorToStringSecurityDescriptor kemudian dapat digunakan sebagai nilai parameter strAllUserProfileSecurity saat memanggil WlanSetProfile.

Untuk setiap profil LAN nirkabel yang digunakan oleh layanan AutoConfig Wifi Asli, Windows mempertahankan konsep data pengguna kustom. Data pengguna kustom ini awalnya tidak ada, tetapi dapat diatur dengan memanggil fungsi WlanSetProfileCustomUserData . Data pengguna kustom akan direset ke kosong setiap kali profil dimodifikasi dengan memanggil fungsi WlanSetProfile . Setelah data pengguna kustom diatur, data ini dapat diakses menggunakan fungsi WlanGetProfileCustomUserData .

Semua fungsi LAN nirkabel memerlukan GUID antarmuka untuk antarmuka nirkabel saat melakukan operasi profil. Ketika antarmuka nirkabel dihapus, statusnya dibersihkan dari Layanan LAN Nirkabel (WLANSVC) dan tidak ada operasi profil yang dimungkinkan.

Fungsi WlanSetProfile dapat gagal dengan ERROR_INVALID_PARAMETER jika antarmuka nirkabel yang ditentukan dalam parameter pInterfaceGuid telah dihapus dari sistem (adaptor nirkabel USB yang telah dihapus, misalnya).

Perintah tambahkan profil wlan netsh menyediakan fungsionalitas serupa di baris perintah. Untuk informasi selengkapnya, lihat Perintah Netsh untuk Jaringan Area Lokal Nirkabel (wlan).

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista, Windows XP dengan SP3 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	wlanapi.h (termasuk Wlanapi.h)
Pustaka	Wlanapi.lib
DLL	Wlanapi.dll
Redistribusi	API LAN Nirkabel untuk Windows XP dengan SP2