Fungsi WlanGetNetworkBssList (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 WlanGetNetworkBssList mengambil daftar entri set layanan dasar (BSS) jaringan nirkabel atau jaringan pada antarmuka LAN nirkabel tertentu.

Sintaks

DWORD WlanGetNetworkBssList(
  [in]       HANDLE            hClientHandle,
  [in]       const GUID        *pInterfaceGuid,
  [optional] const PDOT11_SSID pDot11Ssid,
  [in]       DOT11_BSS_TYPE    dot11BssType,
  [in]       BOOL              bSecurityEnabled,
             PVOID             pReserved,
  [out]      PWLAN_BSS_LIST    *ppWlanBssList
);

Parameter

[in] hClientHandle

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

[in] pInterfaceGuid

Penunjuk ke GUID antarmuka LAN nirkabel yang akan dikueri.

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

[optional] pDot11Ssid

Penunjuk ke struktur DOT11_SSID yang menentukan SSID jaringan tempat daftar BSS diminta. Parameter ini bersifat opsional. Ketika diatur ke NULL, daftar yang dikembalikan berisi semua entri BSS yang tersedia pada antarmuka LAN nirkabel.

Jika penunjuk ke struktur DOT11_SSID ditentukan, panjang SSID yang ditentukan dalam anggota uSSIDLength dari struktur DOT11_SSID harus kurang dari atau sama dengan DOT11_SSID_MAX_LENGTH yang ditentukan dalam file header Wlantypes.h . Selain itu, parameter dot11BssType harus diatur ke dot11_BSS_type_infrastructure atau dot11_BSS_type_independent dan parameter bSecurityEnabled harus ditentukan.

[in] dot11BssType

Jenis jaringan BSS. Parameter ini diabaikan jika SSID jaringan untuk daftar BSS tidak ditentukan (parameter pDot11Ssid adalah NULL).

Parameter ini dapat menjadi salah satu nilai berikut yang ditentukan dalam enumerasi DOT11_BSS_TYPE yang ditentukan dalam file header Wlantypes.h .

Nilai	Makna
dot11_BSS_type_infrastructure	Jaringan BSS infrastruktur.
dot11_BSS_type_independent	Jaringan BSS independen (IBSS) (jaringan ad hoc).
dot11_BSS_type_any	Jaringan BSS apa pun.

[in] bSecurityEnabled

Nilai yang menunjukkan apakah keamanan diaktifkan pada jaringan. Parameter ini hanya valid ketika SSID jaringan untuk daftar BSS ditentukan (parameter pDot11Ssid bukan NULL).

pReserved

Disiapkan untuk penggunaan masa mendatang. Parameter ini harus diatur ke NULL.

[out] ppWlanBssList

Penunjuk ke penyimpanan untuk penunjuk guna menerima daftar entri BSS yang dikembalikan dalam struktur WLAN_BSS_LIST .

Buffer untuk WLAN_BSS_LIST yang dikembalikan dialokasikan oleh fungsi WlanGetNetworkBssList jika panggilan berhasil.

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 hClientHandle tidak ditemukan dalam tabel handel.
ERROR_INVALID_PARAMETER	Parameter salah. Kesalahan ini dikembalikan jika parameter hClientHandle, pInterfaceGuid, atau ppWlanBssList adalah NULL. Kesalahan ini dikembalikan jika pReserved bukan NULL. Kesalahan ini juga dikembalikan jika hClientHandle, SSID yang ditentukan dalam parameter pDot11Ssid , atau jenis BSS yang ditentukan dalam parameter dot11BssType tidak valid.
ERROR_NDIS_DOT11_POWER_STATE_INVALID	Radio yang terkait dengan antarmuka dimatikan. Daftar BSS tidak tersedia saat radio mati.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup tersedia untuk memproses permintaan ini dan mengalokasikan memori untuk hasil kueri.
ERROR_NOT_FOUND	Elemen tidak ditemukan. Kesalahan ini dikembalikan jika GUID antarmuka yang akan dikueri yang ditentukan dalam parameter pInterfaceGuid tidak dapat ditemukan.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika fungsi ini dipanggil dari Windows XP dengan SP3 atau Wireless LAN API untuk Windows XP dengan klien SP2. Kesalahan ini juga dikembalikan jika layanan AutoConfig WLAN dinonaktifkan.
ERROR_SERVICE_NOT_ACTIVE	Layanan Konfigurasi Otomatis WLAN belum dimulai.
RPC_STATUS	Berbagai kode kesalahan.

Keterangan

Fungsi WlanGetNetworkBssList mengambil daftar set layanan dasar untuk setiap jaringan nirkabel atau jaringan yang dapat diakses pada antarmuka tertentu. Daftar informasi yang dikembalikan untuk setiap jaringan nirkabel juga berisi daftar elemen informasi yang dikembalikan oleh setiap titik akses untuk jaringan BSS infrastruktur atau serekan jaringan untuk jaringan BSS independen (jaringan ad hoc). Informasi dikembalikan sebagai penunjuk ke struktur WLAN_BSS_LIST dalam parameter ppWlanBssList . Struktur WLAN_BSS_LIST berisi jumlah item diikuti dengan array entri struktur WLAN_BSS_ENTRY .

Karena informasi yang dikembalikan oleh fungsi WlanGetNetworkBssList dikirim oleh titik akses untuk jaringan BSS infrastruktur atau oleh peer jaringan untuk jaringan BSS independen (jaringan ad hoc), informasi yang dikembalikan tidak boleh dipercaya. Anggota ulIeOffset dan ulIeSize dalam struktur WLAN_BSS_ENTRY harus digunakan untuk menentukan ukuran blob data elemen informasi dalam struktur WLAN_BSS_ENTRY , bukan data dalam blob data elemen informasi itu sendiri. Fungsi WlanGetNetworkBssList tidak memvalidasi bahwa informasi apa pun yang dikembalikan dalam blob data elemen informasi yang ditunjukkan oleh anggota ulIeOffset adalah elemen informasi yang valid seperti yang didefinisikan oleh standar IEEE 802.11 untuk LAN nirkabel.

Jika parameter pDot11Ssid ditentukan (bukan NULL), parameter dot11BssType yang ditentukan harus diatur ke dot11_BSS_type_infrastructure untuk jaringan BSS infrastruktur atau dot11_BSS_type_independent untuk jaringan BSS independen (jaringan ad hoc). Jika parameter dot11BssType diatur ke dot11_BSS_type_any, maka fungsi WlanGetNetworkBssList mengembalikan ERROR_SUCCESS tetapi tidak ada entri BSS yang akan dikembalikan.

Untuk mengembalikan daftar semua jaringan BSS infrastruktur dan jaringan BSS independen (jaringan ad hoc) pada antarmuka LAN nirkabel, atur parameter pDot11Ssid ke NULL. Ketika antarmuka LAN nirkabel juga beroperasi sebagai Jaringan Yang Dihosting Nirkabel, daftar BSS akan berisi entri untuk BSS yang dibuat untuk Jaringan Yang Dihosting Nirkabel.

Fungsi WlanGetNetworkBssList mengembalikan ERROR_SUCCESS ketika daftar BSS kosong dikembalikan oleh Layanan Konfigurasi Otomatis WLAN. Aplikasi yang memanggil fungsi WlanGetNetworkBssList harus memeriksa apakah anggota dwNumberOfItems dari WLAN_BSS_LIST yang diarahkan oleh parameter ppWlanBssList bukan nol sebelum mengakses anggota wlanBssEntries[0] dalam struktur WLAN_BSS_LIST .

Fungsi WlanGetNetworkBssList mengalokasikan memori untuk daftar set layanan dasar yang dikembalikan dalam buffer yang diarahkan oleh parameter ppWlanBssList saat fungsi berhasil. Memori yang digunakan untuk buffer yang diarahkan oleh parameter ppWlanBssList harus dirilis dengan memanggil fungsi WlanFreeMemory setelah buffer tidak lagi diperlukan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [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