Fungsi WlanHostedNetworkSetSecondaryKey (wlanapi.h)

Artikel
08/28/2023

Fungsi WlanHostedNetworkSetSecondaryKey mengonfigurasi kunci keamanan sekunder yang akan digunakan oleh Hosted Network nirkabel.

Sintaks

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

Handel sesi klien, dikembalikan oleh panggilan sebelumnya ke fungsi WlanOpenHandle .

[in] dwKeyLength

Jumlah byte data yang valid dalam array data utama yang ditunjukkan oleh parameter pucKeyData . Panjang kunci ini harus mencakup penghentian '\0' jika kuncinya adalah frasa sandi.

[in] pucKeyData

Penunjuk ke buffer yang berisi data kunci. Jumlah byte data yang valid dalam buffer harus setidaknya nilai yang ditentukan dalam parameter dwKeyLength .

[in] bIsPassPhrase

Nilai Boolean yang menunjukkan apakah array data kunci yang diarahkan oleh parameter pucKeyData dalam format frasa sandi.

Jika parameter ini TRUE, array data kunci dalam format frasa sandi. Jika parameter ini FALSE, array data kunci tidak dalam format frasa sandi.

[in] bPersistent

Nilai Boolean yang menunjukkan apakah array data kunci yang ditunjukkan oleh parameter pucKeyData akan disimpan dan digunakan kembali nanti atau hanya untuk penggunaan satu kali.

Jika parameter ini TRUE, array data kunci akan disimpan dan digunakan kembali nanti. Jika parameter ini FALSE, array data kunci akan digunakan untuk satu sesi (baik sesi saat ini atau sesi berikutnya jika Jaringan yang Dihosting tidak dimulai).

[out, optional] pFailReason

Penunjuk opsional ke nilai yang menerima alasan kegagalan, jika panggilan ke fungsi WlanHostedNetworkSetSecondaryKey gagal. Nilai yang mungkin karena alasan kegagalan berasal dari jenis enumerasi WLAN_HOSTED_NETWORK_REASON yang ditentukan dalam file header Wlanapi.h .

pvReserved

Disiapkan untuk penggunaan masa mendatang. Parameter ini harus NULL.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.

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

Menampilkan kode	Deskripsi
ERROR_INVALID_HANDLE	Handel tidak valid. Kesalahan ini dikembalikan jika handel yang ditentukan dalam parameter hClientHandle tidak ditemukan dalam tabel handel.
ERROR_INVALID_PARAMETER	Parameter salah. Kesalahan ini dikembalikan jika salah satu kondisi berikut terjadi: hClientHandle adalah NULL. pucKeyData adalah NULL. pucKeyData tidak menunjuk ke kunci valid yang terbentuk dengan baik. pvReserved bukan NULL.
ERROR_INVALID_STATE	Sumber daya tidak dalam status yang benar untuk melakukan operasi yang diminta. Ini dapat terjadi jika Jaringan Yang Dihosting nirkabel sedang dalam proses mematikan.
ERROR_SERVICE_NOT_ACTIVE	Layanan belum dimulai. Kesalahan ini dikembalikan jika Layanan Konfigurasi Otomatis WLAN tidak berjalan.
Lainnya	Berbagai RPC dan kode kesalahan lainnya. Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi WlanHostedNetworkSetSecondaryKey adalah ekstensi untuk API nirkabel asli yang ditambahkan untuk mendukung Hosted Network nirkabel pada Windows 7 dan pada Windows Server 2008 R2 dengan Layanan LAN Nirkabel terinstal.

Aplikasi klien memanggil fungsi WlanHostedNetworkSetSecondaryKey untuk mengonfigurasi kunci keamanan sekunder yang akan digunakan oleh Hosted Network nirkabel. Setiap perubahan Jaringan yang Dihosting yang disebabkan oleh fungsi ini tidak akan secara otomatis dibatalkan jika aplikasi panggilan menutup handel panggilannya (dengan memanggil WlanCloseHandle dengan parameter hClientHandle ) atau jika proses berakhir.

Setelah dimulai, Jaringan Yang Dihosting nirkabel akan memungkinkan rekan nirkabel untuk mengaitkan dengan kunci keamanan sekunder ini selain kunci keamanan utama. Kunci keamanan sekunder selalu ditentukan oleh pengguna sesuai kebutuhan, sementara kunci keamanan utama dihasilkan oleh sistem operasi dengan kekuatan keamanan yang lebih besar.

Kunci keamanan sekunder yang diteruskan dalam buffer yang ditunjukkan oleh parameter pucKeyData digunakan dengan autentikasi WPA2-Personal dan harus dalam salah satu format berikut:

Frasa sandi kunci yang terdiri dari array karakter ASCII dari 8 hingga 63 karakter. Parameter dwKeyLength harus menyertakan penghentian '\0' dalam frasa sandi. Nilai parameter dwKeyLength harus dalam rentang 9 hingga 64.
Kunci biner yang terdiri dari 32 byte data kunci biner. Parameter dwKeyLength harus 32 untuk kunci biner.

Untuk mengonfigurasi kunci keamanan sekunder yang valid, parameter dwKeyLength harus berada dalam rentang yang benar dan parameter pucKeyData harus menunjuk ke buffer memori yang valid yang berisi byte data yang ditentukan. Untuk menghapus kunci keamanan sekunder yang saat ini dikonfigurasi dari sistem, aplikasi harus memanggil fungsi WlanHostedNetworkSetSecondaryKey dengan nol dalam parameter dwKeyLength dan NULL dalam parameter pucKeyData .

Fungsi WlanHostedNetworkSetSecondaryKey akan mengembalikan ERROR_INVALID_PARAMETER jika parameter pucKeyDataadalah NULL, tetapi parameter dwKeyLength bukan nol. Fungsi WlanHostedNetworkSetSecondaryKey juga akan mengembalikan ERROR_INVALID_PARAMETER jika parameter dwKeyLength nol, tetapi parameter pucKeyData bukan NULL.

Kunci keamanan sekunder biasanya diatur sebelum Jaringan Yang Dihosting nirkabel dimulai. Kemudian akan digunakan lain kali ketika Jaringan yang Dihosting dimulai.

Kunci keamanan sekunder juga dapat diatur setelah Jaringan yang Dihosting dimulai. Dalam hal ini, kunci keamanan sekunder akan segera digunakan. Setiap klien yang menggunakan kunci keamanan sekunder sebelumnya akan tetap terhubung, tetapi mereka tidak akan dapat terhubung kembali jika terputus karena alasan apa pun atau jika Jaringan Yang Dihosting nirkabel dimulai ulang.

Kunci keamanan sekunder dapat ditentukan sebagai persisten jika parameter bPersisten diatur ke TRUE. Ketika ditentukan sebagai persisten, kunci keamanan sekunder akan segera digunakan jika Jaringan yang Dihosting sudah dimulai, dan juga digunakan kembali setiap kali Jaringan yang Dihosting dimulai di masa mendatang.

Jika kunci keamanan sekunder tidak ditentukan sebagai persisten, kunci tersebut akan segera digunakan jika Jaringan yang Dihosting sudah dimulai, atau hanya untuk waktu berikutnya ketika Jaringan yang Dihosting dimulai. Setelah Jaringan yang Dihosting dihentikan, kunci keamanan sekunder ini tidak akan pernah digunakan lagi dan akan dihapus dari sistem.

Setiap pengguna dapat memanggil fungsi ini untuk mengonfigurasi kunci keamanan sekunder yang akan digunakan di Jaringan yang Dihosting. Namun, kemampuan untuk mengaktifkan Jaringan Yang Dihosting nirkabel dapat dibatasi oleh kebijakan grup di domain.

Pada Windows 7 dan yang lebih baru, sistem operasi menginstal perangkat virtual jika adaptor nirkabel yang mampu Jaringan Terhosting ada pada komputer. Perangkat virtual ini biasanya muncul di "Folder Koneksi Jaringan" sebagai 'Koneksi Jaringan Nirkabel 2' dengan Nama Perangkat 'adaptor Miniport Microsoft Virtual WiFi' jika komputer memiliki adaptor jaringan nirkabel tunggal. Perangkat virtual ini digunakan secara eksklusif untuk melakukan koneksi titik akses perangkat lunak (SoftAP) dan tidak ada dalam daftar yang dikembalikan oleh fungsi WlanEnumInterfaces . Masa pakai perangkat virtual ini terkait dengan adaptor nirkabel fisik. Jika adaptor nirkabel fisik dinonaktifkan, perangkat virtual ini juga akan dihapus. Fitur ini juga tersedia di Windows Server 2008 R2 dengan Layanan LAN Nirkabel terinstal.

Persyaratan


Klien minimum yang didukung	Windows 7 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform	Windows
Header	wlanapi.h (termasuk Wlanapi.h)
Pustaka	Wlanapi.lib
DLL	Wlanapi.dll