Fungsi SetIpForwardEntry2 (netioapi.h)

Artikel
08/25/2023

Fungsi SetIpForwardEntry2 mengatur properti entri rute IP di komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Route
);

Parameter

[in] Route

Penunjuk ke entri struktur MIB_IPFORWARD_ROW2 untuk entri rute IP. Anggota DestinationPrefixdari MIB_IPFORWARD_ROW2 harus diatur ke awalan tujuan IP yang valid, anggota NextHop dari MIB_IPFORWARD_ROW2 harus diatur ke keluarga alamat IP dan alamat IP yang valid, dan InterfaceLuid atau anggota InterfaceIndexdari MIB_IPFORWARD_ROW2 harus ditentukan.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah NO_ERROR.

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

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Akses ditolak. Kesalahan ini dikembalikan dalam beberapa kondisi yang mencakup hal berikut: pengguna tidak memiliki hak istimewa administratif yang diperlukan di komputer lokal atau aplikasi tidak berjalan dalam shell yang ditingkatkan sebagai Administrator bawaan (administrator RunAs).
ERROR_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika penunjuk NULL diteruskan dalam parameter Rute , anggota DestinationPrefixdari MIB_IPFORWARD_ROW2 yang diarahkan oleh parameter Rute tidak ditentukan, anggota NextHop dari MIB_IPFORWARD_ROW2 yang diarahkan oleh parameter Rute tidak ditentukan, atau anggota InterfaceLuid atau InterfaceIndexdari MIB_IPFORWARD_ROW2 yang diarahkan oleh Rute parameter tidak ditentukan.
ERROR_NOT_FOUND	Antarmuka yang ditentukan tidak dapat ditemukan. Kesalahan ini dikembalikan jika antarmuka jaringan yang ditentukan oleh anggota InterfaceLuid atau InterfaceIndexdari MIB_IPFORWARD_ROW2 yang diarahkan oleh parameter Rute tidak dapat ditemukan.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi SetIpForwardEntry2 didefinisikan pada Windows Vista dan yang lebih baru.

Fungsi SetIpForwardEntry2 digunakan untuk mengatur properti untuk entri rute IP yang ada di komputer lokal.

Anggota DestinationPrefix dalam struktur MIB_IPFORWARD_ROW2 yang diarahkan oleh parameter Rute harus diinisialisasi ke awalan dan keluarga alamat IP yang valid. Anggota NextHop dalam struktur MIB_IPFORWARD_ROW2 yang diarahkan oleh parameter Rute harus diinisialisasi ke alamat IP dan keluarga yang valid. Selain itu, setidaknya salah satu anggota berikut dalam struktur MIB_IPFORWARD_ROW2 yang diarahkan ke parameter Rute harus diinisialisasi ke antarmuka: InterfaceLuid atau InterfaceIndex.

Bidang digunakan dalam urutan yang tercantum di atas. Jadi, jika InterfaceLuid ditentukan, maka anggota ini digunakan untuk menentukan antarmuka untuk menambahkan alamat IP unicast. Jika tidak ada nilai yang ditetapkan untuk anggota InterfaceLuid (nilai anggota ini diatur ke nol), maka anggota InterfaceIndex berikutnya digunakan untuk menentukan antarmuka.

Offset metrik rute yang ditentukan dalam anggota Metrik dari struktur MIB_IPFORWARD_ROW2 yang diarahkan oleh parameter Rute hanya mewakili bagian dari metrik rute lengkap. Metrik lengkap adalah kombinasi dari offset metrik rute ini yang ditambahkan ke metrik antarmuka yang ditentukan dalam anggota Metrik dari struktur MIB_IPINTERFACE_ROW antarmuka terkait. Aplikasi dapat mengambil metrik antarmuka dengan memanggil fungsi GetIpInterfaceEntry .

Anggota Usia dan Asal dari struktur MIB_IPFORWARD_ROW2 yang ditunjukkan oleh Baris diabaikan ketika fungsi SetIpForwardEntry2 dipanggil. Anggota ini diatur oleh tumpukan jaringan dan tidak dapat diubah menggunakan fungsi SetIpForwardEntry2 .

Fungsi SetIpForwardEntry2 akan gagal jika anggota DestinationPrefix dan NextHopdari MIB_IPFORWARD_ROW2 yang diarahkan oleh parameter Rute tidak cocok dengan entri rute IP pada antarmuka yang ditentukan.

Fungsi SetIpForwardEntry2 hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika SetIpForwardEntry2 dipanggil oleh pengguna yang bukan anggota grup Administrator, panggilan fungsi akan gagal dan ERROR_ACCESS_DENIED dikembalikan.

Fungsi SetIpForwardEntry2 juga dapat gagal karena kontrol akun pengguna (UAC) pada Windows Vista dan yang lebih baru. Jika aplikasi yang berisi fungsi ini dijalankan oleh pengguna yang masuk sebagai anggota grup Administrator selain Administrator bawaan, panggilan ini akan gagal kecuali aplikasi telah ditandai dalam file manifes dengan requestedExecutionLevel yang diatur ke requireAdministrator. Jika aplikasi tidak memiliki file manifes ini, pengguna yang masuk sebagai anggota grup Administrator selain Administrator bawaan kemudian harus menjalankan aplikasi dalam shell yang ditingkatkan sebagai Administrator bawaan (administrator RunAs) agar fungsi ini berhasil.

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