Fungsi NotifyRouteChange2 (netioapi.h)

Artikel
03/15/2023

Fungsi NotifyRouteChange2 mendaftar untuk diberi tahu tentang perubahan entri rute IP di komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyRouteChange2(
  [in]      ADDRESS_FAMILY             AddressFamily,
  [in]      PIPFORWARD_CHANGE_CALLBACK Callback,
  [in]      PVOID                      CallerContext,
  [in]      BOOLEAN                    InitialNotification,
  [in, out] HANDLE                     *NotificationHandle
);

Parameter

[in] AddressFamily

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 rute IPv4.
AF_INET6	Daftar hanya untuk pemberitahuan perubahan rute IPv6.
AF_UNSPEC	Daftar untuk pemberitahuan perubahan rute IPv4 dan IPv6.

[in] Callback

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

[in] CallerContext

Konteks pengguna diteruskan ke fungsi panggilan balik yang ditentukan dalam parameter Panggilan Balik saat pemberitahuan rute IP 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 entri rute 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.

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 NotifyRouteChange2 didefinisikan 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 NotifyRouteChange2 saat mendaftar untuk pemberitahuan.
DI Baris PMIB_IPFORWARD_ROW2 OPSIONAL	Penunjuk ke entri MIB_IPFORWARD_ROW2 untuk entri rute IP 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 NotifyRouteChange2 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 NotifyRouteChange2 . Jika fungsi panggilan balik berada dalam DLL terpisah, maka DLL harus dimuat sebelum memanggil fungsi NotifyRouteChange2 untuk mendaftar pemberitahuan perubahan.

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

Setelah fungsi NotifyRouteChange2 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 jika sistem dimatikan atau di-boot ulang.

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

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


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