Fungsi WlanHostedNetworkQuerySecondaryKey (wlanapi.h)

Artikel
03/15/2023

Fungsi WlanHostedNetworkQuerySecondaryKey meminta kunci keamanan sekunder yang dikonfigurasi untuk digunakan oleh Hosted Network nirkabel.

Sintaks

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

Parameter

[in] hClientHandle

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

[out] pdwKeyLength

Penunjuk ke nilai yang menentukan jumlah byte data yang valid dalam array data utama yang ditujukkan oleh parameter ppucKeyData , jika panggilan ke fungsi WlanHostedNetworkQuerySecondaryKey berhasil.

Panjang kunci ini mencakup penghentian '\0' jika kuncinya adalah frasa sandi.

[out] ppucKeyData

Penunjuk ke nilai yang menerima penunjuk ke buffer yang dikembalikan dengan data kunci keamanan sekunder, jika panggilan ke fungsi WlanHostedNetworkQuerySecondaryKey berhasil.

[out] pbIsPassPhrase

Penunjuk ke nilai Boolean yang menunjukkan apakah array data kunci yang ditunjukkan oleh parameter ppucKeyData 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.

[out] pbPersistent

Penunjuk ke nilai Boolean yang menunjukkan apakah array data kunci yang ditunjukkan oleh parameter ppucKeyData akan disimpan dan digunakan kembali nanti atau hanya untuk penggunaan satu kali.

Jika parameter ini TRUE, array data utama akan disimpan dan digunakan kembali nanti. Jika parameter ini FALSE, array data kunci hanya untuk penggunaan satu kali.

[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 adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan mungkin merupakan 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. pdwKeyLength adalah NULL. ppucKeyData adalah NULL atau tidak valid. pbIsPassPhrase adalah NULL atau tidak valid. pbPersistent adalah NULL. 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_OUTOFMEMORY	Penyimpanan yang tersedia tidak cukup untuk menyelesaikan operasi ini.
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 WlanHostedNetworkQuerySecondaryKey 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 diinstal.

Aplikasi klien memanggil fungsi WlanHostedNetworkQuerySecondaryKey untuk mengkueri kunci keamanan sekunder yang akan digunakan oleh Hosted Network nirkabel. Fungsi ini akan mengembalikan informasi utama termasuk data kunci, panjang kunci, apakah itu frasa sandi, dan apakah itu persisten atau untuk penggunaan satu kali. Fungsi ini tidak mengubah status atau properti Jaringan Yang Dihosting nirkabel.

Kunci keamanan sekunder adalah frasa sandi jika nilai yang diarahkan oleh parameter pbIsPassPhrase adalah TRUE. Kunci keamanan sekunder adalah kunci biner jika nilai yang diarahkan oleh parameter pbIsPassPhrase adalah FALSE.

Kunci keamanan sekunder yang dikembalikan dalam buffer yang diacu oleh parameter ppucKeyData digunakan dengan autentikasi WPA2-Personal dan berada dalam salah satu format berikut:

Frasa sandi kunci yang terdiri dari array karakter ASCII dari 8 hingga 63 karakter. Nilai yang diarahkan oleh parameter pdwKeyLength menyertakan penghentian '\0' dalam frasa sandi. Nilai yang diarahkan oleh parameter pdwKeyLength harus berada di kisaran 9 hingga 64.
Kunci biner yang terdiri dari 32 byte data kunci biner. Nilai yang diarahkan oleh parameter pdwKeyLength harus 32 untuk kunci biner.

Kunci keamanan sekunder persisten jika nilai yang ditujukan oleh parameter pbPersistent adalah TRUE. Ketika 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.

Jika tidak ada kunci keamanan sekunder yang saat ini dikonfigurasi, nilai yang dikembalikan yang diarahkan oleh parameter pdwKeyLength akan menjadi nol, dan nilai yang dikembalikan dalam parameter ppucKeyData akan menjadi NULL. Dalam kasus seperti itu, nilai yang dikembalikan dalam parameter pbIsPassPhrase dan pbPersistent tidak akan berarti.

Jika fungsi WlanHostedNetworkQuerySecondaryKey berhasil, memori yang digunakan untuk buffer dalam parameter ppucKeyData yang dikembalikan harus dibebaskan setelah digunakan dengan memanggil fungsi WlanFreeMemory .

Setiap pengguna dapat memanggil fungsi WlanHostedNetworkQuerySecondaryKey untuk mengkueri kunci keamanan sekunder yang 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 di komputer. Perangkat virtual ini biasanya muncul di "Folder Koneksi Jaringan" sebagai 'Koneksi Jaringan Nirkabel 2' dengan Nama Perangkat 'Adaptor Mini WiFi Virtual Microsoft' 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 dilepas. 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