Fungsi NotifyStableUnicastIpAddressTable (netioapi.h)

Artikel
08/25/2023

Fungsi NotifyStableUnicastIpAddressTable mengambil tabel alamat IP unicast yang stabil di komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
  [in]      ADDRESS_FAMILY                           Family,
  [in, out] PMIB_UNICASTIPADDRESS_TABLE              *Table,
  [in]      PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  [in]      PVOID                                    CallerContext,
  [in, out] HANDLE                                   *NotificationHandle
);

Parameter

[in] Family

Keluarga alamat yang akan diambil.

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 mana pun 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 mengambil tabel alamat IP unicast stabil yang berisi entri IPv4 dan IPv6.
AF_INET 2	Keluarga alamat Protokol Internet versi 4 (IPv4). Ketika parameter ini ditentukan, fungsi mengambil tabel alamat IP unicast stabil yang hanya berisi entri IPv4.
AF_INET6 23	Keluarga alamat Protokol Internet versi 6 (IPv6). Ketika parameter ini ditentukan, fungsi mengambil tabel alamat IP unicast stabil yang hanya berisi entri IPv6.

[in, out] Table

Penunjuk ke struktur MIB_UNICASTIPADDRESS_TABLE . Ketika NotifyStableUnicastIpAddressTable berhasil, parameter ini mengembalikan tabel alamat IP unicast yang stabil di komputer lokal.

Ketika NotifyStableUnicastIpAddressTable mengembalikan ERROR_IO_PENDING menunjukkan bahwa permintaan I/O tertunda, tabel alamat IP unicast yang stabil dikembalikan ke fungsi dalam parameter CallerCallback .

[in] CallerCallback

Penunjuk ke fungsi untuk memanggil dengan tabel alamat IP unicast yang stabil. Fungsi ini akan dipanggil jika NotifyStableUnicastIpAddressTable mengembalikan ERROR_IO_PENDING, menunjukkan bahwa permintaan I/O tertunda.

[in] CallerContext

Konteks pengguna diteruskan ke fungsi panggilan balik yang ditentukan dalam parameter CallerCallback saat tabel alamat IP unicast stabil si tersedia.

[in, out] NotificationHandle

Pointer yang digunakan untuk mengembalikan handel yang dapat digunakan untuk membatalkan permintaan untuk mengambil tabel alamat IP unicast yang stabil. Parameter ini dikembalikan jika nilai pengembalian dari NotifyStableUnicastIpAddressTableERROR_IO_PENDING menunjukkan bahwa permintaan I/O tertunda.

Mengembalikan nilai

Jika fungsi segera berhasil, nilai yang dikembalikan NO_ERROR dan tabel IP unicast yang stabil dikembalikan dalam parameter Tabel .

Jika permintaan I/O tertunda, fungsi mengembalikan ERROR_IO_PENDING dan fungsi yang ditunjukkan oleh parameter CallerCallback dipanggil ketika permintaan I/O telah selesai dengan tabel alamat IP unicast yang stabil.

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 Tabel adalah penunjuk NULL , parameter NotificationHandle adalah pointer NULL , atau 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 NotifyStableUnicastIpAddressTable didefinisikan pada Windows Vista dan yang lebih baru.

Jika fungsi NotifyStableUnicastIpAddressTable segera berhasil, nilai yang dikembalikan NO_ERROR dan tabel IP unicast yang stabil dikembalikan dalam parameter Tabel . Aplikasi panggilan harus membebaskan memori yang ditujukan oleh parameter Tabel menggunakan fungsi FreeMibTable ketika informasi MIB_UNICASTIPADDRESS_TABLE tidak lagi diperlukan.

Semua alamat IP unicast kecuali alamat dial-on-demand dianggap stabil hanya jika berada dalam status yang disukai. Untuk entri alamat IP unicast normal, ini akan sesuai dengan anggota DadState dari MIB_UNICASTIPADDRESS_ROW untuk alamat IP yang diatur ke IpDadStatePreferred. Setiap alamat dial-on-demand mendefinisikan metrik stabilitasnya sendiri. Saat ini satu-satunya alamat dial-on-demand yang dipertimbangkan oleh fungsi ini adalah alamat IP unicast yang digunakan oleh klien Teredo di komputer lokal.

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

Ketika NotifyStableUnicastIpAddressTable berhasil dan mengembalikan NO_ERROR, parameter Tabel mengembalikan tabel alamat IP unicast yang stabil di komputer lokal.

Fungsi NotifyStableUnicastIpAddressTable digunakan terutama oleh aplikasi yang menggunakan klien Teredo.

Jika alamat IP unicast yang digunakan oleh Teredo tersedia di komputer lokal tetapi tidak dalam status stabil (memenuhi syarat), NotifyStableUnicastIpAddressTable mengembalikan ERROR_IO_PENDING dan tabel alamat IP unicast yang stabil akhirnya dikembalikan dengan memanggil fungsi dalam parameter CallerCallback . Jika alamat Teredo tidak tersedia atau dalam status stabil dan alamat IP unicast lainnya dalam keadaan stabil, maka fungsi dalam parameter CallerCallback tidak akan pernah dipanggil.

Fungsi panggilan balik yang ditentukan dalam parameter CallerCallback harus didefinisikan sebagai fungsi jenis VOID. Parameter yang diteruskan ke fungsi panggilan balik meliputi yang berikut ini:

Parameter	Deskripsi
DALAM PVOID CallerContext	Parameter CallerContext diteruskan ke fungsi NotifyStableUnicastIpAddressTable saat mendaftar untuk pemberitahuan.
DI PMIB_UNICASTIPADDRESS_TABLE AddressTable	Penunjuk ke MIB_UNICASTIPADDRESS_TABLE yang berisi tabel alamat IP unicast stabil di komputer lokal.

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

Memori yang dialokasikan oleh parameter AddressTable yang digunakan dalam indikasi panggilan balik dialokasikan oleh sistem operasi. Aplikasi yang menerima pemberitahuan harus membebaskan memori yang ditujukan oleh parameter AddressTable menggunakan fungsi FreeMibTable saat informasi MIB_UNICASTIPADDRESS_TABLE tidak lagi diperlukan.

Setelah fungsi NotifyStableUnicastIpAddressTable dipanggil untuk mendaftar pemberitahuan perubahan, pemberitahuan ini akan terus dikirim hingga aplikasi membatalkan pendaftaran untuk pemberitahuan perubahan atau aplikasi berakhir. Jika aplikasi dihentikan, sistem akan secara otomatis membatalkan pendaftaran apa pun untuk pemberitahuan perubahan. Masih disarankan agar aplikasi secara eksplisit membatalkan pendaftaran 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 meneruskan parameter NotificationHandle yang dikembalikan oleh NotifyStableUnicastIpAddressTable.

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 mengeksekusi 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, di mana 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