Fungsi WlanScan (wlanapi.h)

Artikel
10/19/2023

Catatan

Beberapa informasi berkaitan dengan produk yang telah dirilis sebelumnya, yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Penting

API ini akan dipengaruhi oleh perubahan perilaku sistem operasi yang akan datang, yang direncanakan pada musim gugur 2024. Untuk informasi selengkapnya, lihat Perubahan perilaku API untuk akses dan lokasi Wi-Fi.

Fungsi WlanScan meminta pemindaian untuk jaringan yang tersedia pada antarmuka yang ditunjukkan.

Sintaks

DWORD WlanScan(
  [in]           HANDLE               hClientHandle,
  [in]           const GUID           *pInterfaceGuid,
  [in, optional] const PDOT11_SSID    pDot11Ssid,
  [in, optional] const PWLAN_RAW_DATA pIeData,
                 PVOID                pReserved
);

Parameter

[in] hClientHandle

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

[in] pInterfaceGuid

GUID antarmuka yang akan dikueri.

GUID dari setiap antarmuka LAN nirkabel yang diaktifkan pada komputer lokal dapat ditentukan menggunakan fungsi WlanEnumInterfaces .

[in, optional] pDot11Ssid

Penunjuk ke struktur DOT11_SSID yang menentukan SSID jaringan yang akan dipindai. Parameter ini bersifat opsional. Ketika diatur ke NULL, daftar yang dikembalikan berisi semua jaringan yang tersedia. Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Parameter ini harus NULL.

[in, optional] pIeData

Penunjuk ke elemen informasi untuk disertakan dalam permintaan pemeriksaan. Parameter ini menunjuk ke struktur WLAN_RAW_DATA yang mungkin mencakup informasi ketersediaan provisi klien dan persyaratan autentikasi 802.1X. Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Parameter ini harus NULL.

pReserved

Disiapkan untuk penggunaan masa mendatang. Harus diatur ke 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_PARAMETER	hClientHandleNULL atau tidak valid, pInterfaceGuid adalah NULL, atau pReserved bukan NULL.
ERROR_INVALID_HANDLE	Handel hClientHandle tidak ditemukan dalam tabel handel.
RPC_STATUS	Berbagai kode kesalahan.
ERROR_NOT_ENOUGH_MEMORY	Gagal mengalokasikan memori untuk hasil kueri.

Keterangan

Fungsi WlanScan meminta agar driver LAN Nirkabel 802.11 asli memindai jaringan nirkabel yang tersedia. Driver mungkin atau mungkin tidak mengirim permintaan pemeriksaan (pemindaian aktif) tergantung pada implementasinya dan nilai yang diteruskan dalam parameter pDot11Ssid dan pIeData .

Jika parameter pIeData bukan NULL, driver akan mengirim permintaan pemeriksaan selama pemindaian. Permintaan pemeriksaan mencakup elemen informasi (IE) yang ditunjukkan oleh parameter pIeData . Misalnya, IE Wi-Fi Protected Setup (WPS) dapat disertakan dalam permintaan pemeriksaan untuk menemukan titik akses berkemampuan WPS. Buffer yang ditunjukkan oleh parameter pIeData harus berisi IE lengkap mulai dari ID Element.

Parameter pIeData yang diteruskan ke fungsi WlanScan dapat berisi penunjuk ke struktur WLAN_RAW_DATA opsional yang berisi entri data IE penemuan layanan kedekatan (PSD).

Ketika digunakan untuk menyimpan PSD IE, konstanta DOT11_PSD_IE_MAX_DATA_SIZE yang ditentukan dalam file header Wlanapi.h adalah nilai maksimum anggota dwDataSize .

Terus-menerus	Nilai	Deskripsi
DOT11_PSD_IE_MAX_DATA_SIZE	240	Ukuran data maksimum, dalam byte, dari entri data IE PSD.

Untuk informasi selengkapnya tentang IEs PSD, termasuk diskusi tentang format IE PSD, lihat fungsi WlanSetPsdIEDataList .

Ketika fungsi WlanScan dipanggil, driver LAN Nirkabel 802.11 asli dapat menghapus daftar jaringan nirkabel yang tersedia saat ini sebelum pemindaian dimulai. Aplikasi tidak boleh berasumsi bahwa memanggil fungsi WlanScan akan ditambahkan ke daftar jaringan nirkabel yang tersedia yang ada yang dikembalikan oleh fungsi WlanGetNetworkBssList atau WlanGetAvailableNetworkList dari pemindaian sebelumnya.

Fungsi WlanScan segera kembali. Untuk diberi tahu ketika pemindaian jaringan selesai, klien di Windows Vista dan kemudian harus mendaftar untuk pemberitahuan dengan memanggil WlanRegisterNotification. Parameter dwNotifSource yang diteruskan ke fungsi WlanRegisterNotification harus mengatur bit WLAN_NOTIFICATION_SOURCE_ACM untuk mendaftar pemberitahuan yang dihasilkan oleh modul konfigurasi otomatis. Driver jaringan nirkabel yang memenuhi persyaratan logo Windows diperlukan untuk menyelesaikan permintaan fungsi WlanScan dalam 4 detik.

Layanan LAN Nirkabel tidak mengirim pemberitahuan ketika jaringan nirkabel yang tersedia berubah. Layanan LAN Nirkabel tidak melacak perubahan pada daftar jaringan yang tersedia di beberapa pemindaian. Perilaku default saat ini adalah bahwa Layanan LAN Nirkabel hanya meminta driver antarmuka nirkabel untuk memindai jaringan nirkabel setiap 60 detik, dan dalam beberapa kasus (ketika sudah terhubung ke jaringan nirkabel) Layanan LAN Nirkabel tidak meminta pemindaian sama sekali. Fungsi WlanScan dapat digunakan oleh aplikasi untuk melacak perubahan jaringan nirkabel. Aplikasi harus terlebih dahulu mendaftar untuk pemberitahuan WLAN_NOTIFICATION_SOURCE_ACM. Fungsi WlanScan kemudian dapat dipanggil untuk memulai pemindaian. Aplikasi kemudian harus menunggu untuk menerima pemberitahuan wlan_notification_acm_scan_complete atau batas waktu setelah 4 detik. Kemudian aplikasi dapat memanggil fungsi WlanGetNetworkBssList atau WlanGetAvailableNetworkList untuk mengambil daftar jaringan nirkabel yang tersedia. Proses ini dapat diulang secara berkala dengan aplikasi yang melacak perubahan pada jaringan nirkabel yang tersedia.

Fungsi WlanScan segera kembali dan tidak memberikan pemberitahuan ketika pemindaian selesai pada Windows XP dengan SP3 atau WIRELESS LAN API untuk Windows XP dengan SP2.

Karena menjadi lebih sulit bagi antarmuka nirkabel untuk mengirim dan menerima paket data saat pemindaian terjadi, fungsi WlanScan dapat meningkatkan latensi sampai pemindaian jaringan selesai.

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