Fungsi NotifyUnicastIpAddressChange (netioapi.h)

Artikel
03/15/2023

Fungsi NotifyUnicastIpAddressChange mendaftar untuk diberi tahu tentang perubahan pada semua antarmuka IP unicast, alamat IPv4 unicast, atau alamat IPv6 unicast di komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyUnicastIpAddressChange(
  [in]      ADDRESS_FAMILY                     Family,
  [in]      PUNICAST_IPADDRESS_CHANGE_CALLBACK Callback,
  [in]      PVOID                              CallerContext,
  [in]      BOOLEAN                            InitialNotification,
  [in, out] HANDLE                             *NotificationHandle
);

Parameter

[in] Family

Keluarga alamat tempat mendaftar untuk pemberitahuan perubahan.

Nilai yang mungkin untuk keluarga alamat tercantum dalam file header Winsock2.h . Perhatikan bahwa nilai untuk keluarga alamat AF_ dan konstanta keluarga protokol PF_ identik (misalnya, AF_INET dan PF_INET), sehingga konstanta dapat digunakan.

Pada Windows SDK yang dirilis untuk Windows Vista dan yang lebih baru, organisasi file header telah berubah dan nilai yang mungkin untuk anggota ini ditentukan dalam file header Ws2def.h . Perhatikan bahwa file header Ws2def.h secara otomatis disertakan dalam Winsock2.h, dan tidak boleh digunakan secara langsung.

Nilai yang saat ini didukung adalah AF_INET, AF_INET6, dan AF_UNSPEC.

Nilai	Makna
AF_INET	Daftar hanya untuk pemberitahuan perubahan alamat IPv4 unicast.
AF_INET6	Daftar hanya untuk pemberitahuan perubahan alamat IPv6 unicast.
AF_UNSPEC	Daftar untuk pemberitahuan perubahan alamat IPv4 dan IPv6 unicast.

[in] Callback

Penunjuk ke fungsi untuk dipanggil saat perubahan terjadi. Fungsi ini akan dipanggil ketika pemberitahuan alamat IP unicast diterima.

[in] CallerContext

Konteks pengguna diteruskan ke fungsi panggilan balik yang ditentukan dalam parameter Panggilan Balik saat pemberitahuan antarmuka diterima.

[in] InitialNotification

Nilai yang menunjukkan apakah panggilan balik harus dipanggil segera setelah pendaftaran untuk pemberitahuan perubahan selesai. Pemberitahuan awal ini tidak menunjukkan perubahan yang terjadi pada alamat IP unicast. Tujuan parameter ini untuk memberikan konfirmasi bahwa panggilan balik terdaftar.

[in, out] NotificationHandle

Penunjuk yang digunakan untuk mengembalikan handel yang nantinya dapat digunakan untuk membatalkan pendaftaran pemberitahuan perubahan. Jika berhasil, handel pemberitahuan dikembalikan dalam parameter ini. Jika terjadi kesalahan, NULL dikembalikan.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan NO_ERROR.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
ERROR_INVALID_HANDLE	Terjadi kesalahan internal di mana handel tidak valid ditemukan.
ERROR_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika parameter Family tidak AF_INET, AF_INET6, atau AF_UNSPEC.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi NotifyUnicastIpAddressChange ditentukan pada Windows Vista dan yang lebih baru.

Parameter Keluarga harus diatur ke AF_INET, AF_INET6, atau AF_UNSPEC.

Pemanggilan fungsi panggilan balik yang ditentukan dalam parameter Panggilan Balik diserialisasikan. Fungsi panggilan balik harus didefinisikan sebagai fungsi jenis VOID. Parameter yang diteruskan ke fungsi panggilan balik meliputi yang berikut:

Parameter	Deskripsi
IN PVOID CallerContext	Parameter CallerContext diteruskan ke fungsi NotifyUnicastIpAddressChange saat mendaftar untuk pemberitahuan.
DI Baris PMIB_UNICASTIPADDRESS_ROW OPSIONAL	Penunjuk ke entri MIB_UNICASTIPADDRESS_ROW untuk alamat IP unicast yang diubah. Parameter ini adalah penunjuk NULL ketika nilai MIB_NOTIFICATION_TYPE diteruskan dalam parameter NotificationType ke fungsi panggilan balik diatur ke MibInitialNotification. Ini hanya dapat terjadi jika parameter InitialNotification yang diteruskan ke NotifyUnicastIpAddressChange diatur ke TRUE saat mendaftar untuk pemberitahuan.
IN MIB_NOTIFICATION_TYPE NotificationType	Jenis pemberitahuan. Anggota ini dapat menjadi salah satu nilai dari jenis enumerasi MIB_NOTIFICATION_TYPE yang ditentukan dalam file header Netioapi.h .

Fungsi panggilan balik yang ditentukan dalam parameter Callback harus diimplementasikan dalam proses yang sama dengan aplikasi yang memanggil fungsi NotifyUnicastIpAddressChange . Jika fungsi panggilan balik berada dalam DLL terpisah, maka DLL harus dimuat sebelum memanggil fungsi NotifyUnicastIpAddressChange untuk mendaftar pemberitahuan perubahan.

Ketika fungsi panggilan balik diterima ketika perubahan terjadi dan parameter Baris bukan NULL, penunjuk ke struktur MIB_UNICASTIPADDRESS_ROW yang diteruskan dalam parameter Baris berisi data yang tidak lengkap. Informasi yang dikembalikan dalam struktur MIB_UNICASTIPADDRESS_ROW hanya informasi yang cukup bahwa aplikasi dapat memanggil fungsi GetUnicastIpAddressEntry untuk mengkueri informasi lengkap tentang alamat IP yang berubah. Ketika fungsi panggilan balik diterima, aplikasi harus mengalokasikan struktur MIB_UNICASTIPADDRESS_ROW dan menginisialisasinya dengan anggota Address, InterfaceLuid dan InterfaceIndex dalam struktur MIB_UNICASTIPADDRESS_ROW yang ditunjukkan oleh parameter Baris yang diterima. Penunjuk ke struktur MIB_UNICASTIPADDRESS_ROW yang baru diinisialisasi ini harus diteruskan ke fungsi GetUnicastIpAddressEntry untuk mengambil informasi lengkap tentang alamat IP unicast yang diubah.

Memori yang ditunjukkan oleh parameter Baris yang digunakan dalam indikasi panggilan balik dikelola oleh sistem operasi. Aplikasi yang menerima pemberitahuan tidak boleh mencoba membebaskan memori yang ditunjukkan oleh parameter Baris .

Setelah fungsi NotifyUnicastIpAddressChange dipanggil untuk mendaftar pemberitahuan perubahan, pemberitahuan ini akan terus dikirim sampai aplikasi membatalkan pendaftaran untuk pemberitahuan perubahan atau aplikasi berakhir. Jika aplikasi berakhir, sistem akan secara otomatis membatalkan pendaftaran apa pun untuk pemberitahuan perubahan. Masih disarankan agar aplikasi secara eksplisit membatalkan pendaftaran untuk pemberitahuan perubahan sebelum berakhir.

Pendaftaran apa pun untuk pemberitahuan perubahan tidak bertahan jika sistem dimatikan atau di-boot ulang.

Untuk membatalkan pendaftaran pemberitahuan perubahan, panggil fungsi CancelMibChangeNotify2 yang melewati parameter NotificationHandle yang dikembalikan oleh NotifyUnicastIpAddressChange.

Aplikasi tidak dapat melakukan panggilan ke fungsi CancelMibChangeNotify2 dari konteks utas yang saat ini menjalankan fungsi panggilan balik pemberitahuan untuk parameter NotificationHandle yang sama. Jika tidak, utas yang menjalankan panggilan balik tersebut akan mengakibatkan kebuntuan. Jadi fungsi CancelMibChangeNotify2 tidak boleh dipanggil langsung sebagai bagian dari rutinitas panggilan balik pemberitahuan. Dalam situasi yang lebih umum, utas yang menjalankan fungsi CancelMibChangeNotify2 tidak dapat memiliki sumber daya tempat utas yang menjalankan operasi panggilan balik pemberitahuan akan menunggu karena akan mengakibatkan kebuntuan serupa. Fungsi CancelMibChangeNotify2 harus dipanggil dari utas yang berbeda, tempat utas yang menerima panggilan balik pemberitahuan tidak memiliki dependensi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	netioapi.h (termasuk Iphlpapi.h)
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll