Fungsi NotifyIpInterfaceChange (netioapi.h)

Artikel
03/15/2023

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

Sintaks

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyIpInterfaceChange(
  [in]      ADDRESS_FAMILY               Family,
  [in]      PIPINTERFACE_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_UNSPEC 0	Keluarga alamat tidak ditentukan. Ketika parameter ini ditentukan, fungsi ini mendaftar untuk pemberitahuan perubahan IPv4 dan IPv6.
AF_INET 2	Keluarga alamat Protokol Internet versi 4 (IPv4). Ketika parameter ini ditentukan, fungsi ini hanya mendaftar untuk pemberitahuan perubahan IPv4.
AF_INET6 23	Keluarga alamat Protokol Internet versi 6 (IPv6). Ketika parameter ini ditentukan, fungsi ini hanya mendaftar untuk pemberitahuan perubahan IPv6.

[in] Callback

Penunjuk ke fungsi untuk dipanggil saat perubahan terjadi. Fungsi ini akan dipanggil ketika pemberitahuan antarmuka 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 antarmuka IP. 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.

Mengembalikan nilai

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 NotifyIpInterfaceChange 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 NotifyIpInterfaceChange saat mendaftar untuk pemberitahuan.
DI Baris PMIB_IPINTERFACE_ROW OPSIONAL	Penunjuk ke entri MIB_IPINTERFACE_ROW untuk antarmuka 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 NotifyIpInterfaceChange 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 NotifyIpInterfaceChange . Jika fungsi panggilan balik berada dalam DLL terpisah, maka DLL harus dimuat sebelum memanggil fungsi NotifyIpInterfaceChange untuk mendaftar pemberitahuan perubahan.

Ketika fungsi panggilan balik diterima ketika perubahan terjadi dan parameter Baris bukan NULL, penunjuk ke struktur MIB_IPINTERFACE_ROW yang diteruskan dalam parameter Baris berisi data yang tidak lengkap. Informasi yang dikembalikan dalam struktur MIB_IPINTERFACE_ROW hanya informasi yang cukup bahwa aplikasi dapat memanggil fungsi GetIpInterfaceEntry untuk mengkueri informasi lengkap pada antarmuka IP yang berubah. Ketika fungsi panggilan balik diterima, aplikasi harus mengalokasikan struktur MIB_IPINTERFACE_ROW dan menginisialisasinya dengan anggota Family, InterfaceLuid dan InterfaceIndex dalam struktur MIB_IPINTERFACE_ROW yang ditunjukkan oleh parameter Baris yang diterima. Penunjuk ke struktur MIB_IPINTERFACE_ROW yang baru diinisialisasi ini harus diteruskan ke fungsi GetIpInterfaceEntry untuk mengambil informasi lengkap tentang antarmuka IP 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 .

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

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.

Setelah fungsi NotifyIpInterfaceChange dipanggil untuk mendaftar pemberitahuan perubahan, pemberitahuan ini akan terus dikirim hingga aplikasi membatalkan pendaftaran 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 di seluruh sistem yang dimatikan atau di-boot ulang.

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	netioapi.h (termasuk Iphlpapi.h)
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll