Fungsi WlanRegisterNotification (wlanapi.h)
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 |
---|---|
|
Membatalkan pendaftaran pemberitahuan. |
|
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. |
|
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. |
|
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. |
|
Mendaftar untuk pemberitahuan yang dihasilkan oleh 802.1X. |
|
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. |
|
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. |
|
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. |
|
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 |
---|---|
|
Parameter salah. Kesalahan ini dikembalikan jika hClientHandleNULL atau tidak valid atau jika pReserved bukan NULL. |
|
Handel hClientHandle tidak ditemukan dalam tabel handel. |
|
Gagal mengalokasikan memori untuk hasil kueri. |
|
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. |
|
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 |