Fungsi WlanRegisterNotification (wlanapi.h)

Artikel
03/04/2024

Penting

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

Fungsi WlanRegisterNotification digunakan untuk mendaftarkan dan membatalkan pendaftaran pemberitahuan pada semua antarmuka nirkabel.

Sintaks

DWORD WlanRegisterNotification(
  [in]            HANDLE                     hClientHandle,
  [in]            DWORD                      dwNotifSource,
  [in]            BOOL                       bIgnoreDuplicate,
  [in, optional]  WLAN_NOTIFICATION_CALLBACK funcCallback,
  [in, optional]  PVOID                      pCallbackContext,
  [in]            PVOID                      pReserved,
  [out, optional] PDWORD                     pdwPrevNotifSource
);

Parameter

[in] hClientHandle

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

[in] dwNotifSource

Sumber pemberitahuan yang akan didaftarkan. Bendera ini dapat digabungkan. Ketika parameter ini diatur ke WLAN_NOTIFICATION_SOURCE_NONE, WlanRegisterNotification membatalkan pendaftaran pemberitahuan pada semua antarmuka nirkabel.

Nilai yang mungkin untuk parameter ini ditentukan dalam file header Wlanapi.h dan L2cmn.h .

Tabel berikut ini memperlihatkan kemungkinan nilai.

Nilai	Makna
WLAN_NOTIFICATION_SOURCE_NONE	Membatalkan pendaftaran pemberitahuan.
WLAN_NOTIFICATION_SOURCE_ALL	Mendaftar untuk semua pemberitahuan yang tersedia pada versi sistem operasi, termasuk yang dihasilkan oleh modul 802.1X. Untuk Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2, mengatur dwNotifSource ke WLAN_NOTIFICATION_SOURCE_ALL secara fungsional setara dengan mengatur dwNotifSource ke WLAN_NOTIFICATION_SOURCE_ACM.
WLAN_NOTIFICATION_SOURCE_ACM	Mendaftar untuk pemberitahuan yang dihasilkan oleh modul konfigurasi otomatis. Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Hanya pemberitahuan wlan_notification_acm_connection_complete dan wlan_notification_acm_disconnected yang tersedia.
WLAN_NOTIFICATION_SOURCE_HNWK	Mendaftar untuk pemberitahuan yang dihasilkan oleh Hosted Network nirkabel. Sumber pemberitahuan ini tersedia pada Windows 7 dan pada Windows Server 2008 R2 dengan Layanan LAN Nirkabel terinstal.
WLAN_NOTIFICATION_SOURCE_ONEX	Mendaftar untuk pemberitahuan yang dihasilkan oleh 802.1X.
WLAN_NOTIFICATION_SOURCE_MSM	Mendaftar untuk pemberitahuan yang dihasilkan oleh MSM. Jika bendera WLAN_NOTIFICATION_SOURCE_MSM diatur dalam dwNotifSource, maka kemampuan perangkat wiFiControl diperlukan (lihat Deklarasi kemampuan aplikasi). Jika kemampuan tersebut tidak diberikan, maka fungsi akan mengembalikan ERROR_ACCESS_DENIED. Meminta kemampuan perangkat wiFiControl akan memerlukan persetujuan dari pengguna mengenai akses ke lokasi. Untuk informasi selengkapnya, lihat Perubahan perilaku API untuk akses dan lokasi Wi-Fi. Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Nilai ini tidak didukung.
WLAN_NOTIFICATION_SOURCE_SECURITY	Mendaftar untuk pemberitahuan yang dihasilkan oleh modul keamanan. Saat ini tidak ada pemberitahuan yang ditentukan untuk WLAN_NOTIFICATION_SOURCE_SECURITY. Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Nilai ini tidak didukung.
WLAN_NOTIFICATION_SOURCE_IHV	Mendaftar untuk pemberitahuan yang dihasilkan oleh vendor perangkat keras independen (IHV). Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Nilai ini tidak didukung.
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	Mendaftar untuk pemberitahuan yang dihasilkan oleh layanan perangkat.

Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Parameter ini harus diatur ke WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL, atau WLAN_NOTIFICATION_SOURCE_ACM.

[in] bIgnoreDuplicate

Menentukan apakah pemberitahuan duplikat akan diabaikan. Jika diatur ke TRUE, pemberitahuan tidak akan dikirim ke klien jika identik dengan yang sebelumnya.

Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Parameter ini diabaikan.

[in, optional] funcCallback

Jenis WLAN_NOTIFICATION_CALLBACK yang menentukan jenis fungsi panggilan balik pemberitahuan.

Parameter ini dapat berupa NULL jika parameter dwNotifSource diatur ke WLAN_NOTIFICATION_SOURCE_NONE untuk membatalkan pendaftaran pemberitahuan pada semua antarmuka nirkabel,

[in, optional] pCallbackContext

Penunjuk ke konteks klien yang akan diteruskan ke fungsi panggilan balik dengan pemberitahuan.

[in] pReserved

Disiapkan untuk penggunaan masa mendatang. Harus diatur ke NULL.

[out, optional] pdwPrevNotifSource

Penunjuk ke sumber pemberitahuan yang terdaftar sebelumnya.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.

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

Jika bendera WLAN_NOTIFICATION_SOURCE_MSM diatur dalam dwNotifSource, maka kemampuan perangkat wiFiControl diperlukan (lihat Deklarasi kemampuan aplikasi). Jika kemampuan tersebut tidak diberikan, maka fungsi akan mengembalikan ERROR_ACCESS_DENIED. Meminta kemampuan perangkat wiFiControl akan memerlukan persetujuan dari pengguna mengenai akses ke lokasi. Untuk informasi selengkapnya, lihat Perubahan perilaku API untuk akses dan lokasi Wi-Fi.

Menampilkan kode	Deskripsi
ERROR_INVALID_PARAMETER	Parameter salah. Kesalahan ini dikembalikan jika hClientHandleNULL atau tidak valid atau jika pReserved bukan NULL.
ERROR_INVALID_HANDLE	Handel hClientHandle tidak ditemukan dalam tabel handel.
ERROR_NOT_ENOUGH_MEMORY	Gagal mengalokasikan memori untuk hasil kueri.
ERROR_ACCESS_DENIED	Jika bendera WLAN_NOTIFICATION_SOURCE_MSM diatur dalam dwNotifSource, maka kemampuan perangkat wiFiControl diperlukan (lihat Deklarasi kemampuan aplikasi. Jika kemampuan tersebut tidak diberikan, maka fungsi akan mengembalikan ERROR_ACCESS_DENIED. Meminta kemampuan perangkat wiFiControl akan memerlukan persetujuan dari pengguna mengenai akses ke lokasi. Untuk informasi selengkapnya, lihat Perubahan perilaku API untuk akses dan lokasi Wi-Fi.
RPC_STATUS	Berbagai kode kesalahan.

Keterangan

WlanRegisterNotification digunakan oleh aplikasi untuk mendaftar dan membatalkan pendaftaran pemberitahuan pada semua antarmuka nirkabel. Saat mendaftar untuk pemberitahuan, aplikasi harus menyediakan fungsi panggilan balik yang ditunjukkan oleh parameter funcCallback . Prototipe untuk fungsi panggilan balik ini adalah WLAN_NOTIFICATION_CALLBACK. Fungsi panggilan balik ini akan menerima pemberitahuan yang telah didaftarkan dalam parameter dwNotifSource yang diteruskan ke fungsi WlanRegisterNotification . Fungsi panggilan balik dipanggil dengan penunjuk ke struktur WLAN_NOTIFICATION_DATA sebagai parameter pertama yang berisi informasi terperinci tentang pemberitahuan. Fungsi panggilan balik juga menerima parameter kedua yang berisi penunjuk ke konteks klien yang diteruskan dalam parameter pCallbackContext ke fungsi WlanRegisterNotification .

Fungsi WlanRegisterNotification akan mengembalikan kesalahan jika dwNotifSource adalah nilai selain WLAN_NOTIFICATION_SOURCE_NONE dan klien gagal memberikan fungsi panggilan balik.

Setelah terdaftar, fungsi panggilan balik akan dipanggil setiap kali pemberitahuan tersedia sampai klien membatalkan pendaftaran atau menutup handel.

Setiap pendaftaran untuk menerima pemberitahuan yang disebabkan oleh fungsi ini akan secara otomatis dibatalkan jika aplikasi panggilan menutup handel panggilannya (dengan memanggil WlanCloseHandle dengan parameter hClientHandle ) atau jika proses berakhir.

Jangan panggil WlanRegisterNotification dari fungsi panggilan balik. Jika klien berada di tengah panggilan balik pemberitahuan ketika WlanRegisterNotification dipanggil dengan dwNotifSource diatur ke WLAN_NOTIFICATION_SOURCE_NONE (yaitu, ketika klien membatalkan pendaftaran dari pemberitahuan), maka WlanRegisterNotification akan menunggu panggilan balik selesai sebelum mengembalikan nilai. Memanggil fungsi ini di dalam fungsi panggilan balik akan mengakibatkan panggilan tidak pernah selesai. Jika fungsi panggilan balik dan utas yang membatalkan pendaftaran dari pemberitahuan mencoba memperoleh kunci yang sama, kebuntuan dapat terjadi. Selain itu, jangan panggil WlanRegisterNotification dari fungsi DllMain dalam DLL aplikasi. Ini juga bisa menyebabkan kebuntuan.

Aplikasi dapat kehabisan waktu dan mengkueri status antarmuka saat ini alih-alih menunggu pemberitahuan.

Windows XP dengan SP3 dan WIRELESS LAN API untuk Windows XP dengan SP2: Pemberitahuan ditangani oleh layanan Netman. Jika layanan Netman dinonaktifkan atau tidak tersedia, pemberitahuan tidak akan diterima. Jika pemberitahuan tidak diterima dalam jangka waktu yang wajar, aplikasi harus kehabisan waktu dan mengkueri status antarmuka saat ini.

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