Fungsi CreateIpForwardEntry2 (netioapi.h)

Artikel
03/15/2023

Fungsi CreateIpForwardEntry2 membuat entri rute IP baru di komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API CreateIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Row
);

Parameter

[in] Row

Penunjuk ke entri struktur MIB_IPFORWARD_ROW2 untuk entri rute IP.

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 Baris , anggota DestinationPrefixdari MIB_IPFORWARD_ROW2 yang ditunjukkan oleh parameter Baris tidak ditentukan, anggota NextHop dari MIB_IPFORWARD_ROW2 yang ditunjukkan oleh parameter Baris tidak ditentukan, atau anggota InterfaceLuid atau InterfaceIndexdari MIB_IPFORWARD_ROW2 ditunjukkan oleh Baris parameter tidak ditentukan. Kesalahan ini juga dikembalikan jika anggota PreferredLifetime yang ditentukan dalam MIB_IPFORWARD_ROW2 lebih besar dari anggota ValidLifetime atau jika SitePrefixLength di MIB_IPFORWARD_ROW2 lebih besar dari panjang awalan yang ditentukan dalam DestinationPrefix.
ERROR_NOT_FOUND	Antarmuka yang ditentukan tidak dapat ditemukan. Kesalahan ini dikembalikan jika antarmuka jaringan yang ditentukan oleh anggota InterfaceLuid atau InterfaceIndexdari MIB_IPNET_ROW2 yang ditunjukkan oleh parameter Baris tidak dapat ditemukan.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika antarmuka yang ditentukan tidak mendukung rute. Kesalahan ini juga dikembalikan jika tidak ada tumpukan IPv4 di komputer lokal dan AF_INET ditentukan dalam keluarga alamat di anggota DestinationPrefixdari MIB_IPFORWARD_ROW2 yang ditunjukkan oleh parameter Baris . Kesalahan ini juga dikembalikan jika tidak ada tumpukan IPv6 di komputer lokal dan AF_INET6 ditentukan untuk keluarga alamat di anggota DestinationPrefix .
ERROR_OBJECT_ALREADY_EXISTS	Objek sudah ada. Kesalahan ini dikembalikan jika anggota DestinationPrefix dari MIB_IPFORWARD_ROW2 yang diarahkan oleh parameter Baris adalah duplikat entri rute IP yang ada pada antarmuka yang ditentukan oleh anggota InterfaceLuid atau InterfaceIndex dari MIB_IPFORWARD_ROW2.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi CreateIpForwardEntry2 didefinisikan pada Windows Vista dan yang lebih baru.

Fungsi CreateIpForwardEntry2 digunakan untuk menambahkan entri alamat IP tetangga baru di komputer lokal. Fungsi InitializeIpForwardEntry harus digunakan untuk menginisialisasi anggota entri struktur MIB_IPFORWARD_ROW2 dengan nilai default. Aplikasi kemudian dapat mengubah anggota dalam entri MIB_IPFORWARD_ROW2 yang ingin dimodifikasi, lalu memanggil fungsi CreateIpForwardEntry2 .

Anggota DestinationPrefix dalam struktur MIB_IPFORWARD_ROW2 yang ditunjukkan oleh parameter Baris harus diinisialisasi ke awalan alamat IPv4 atau IPv6 yang valid. Anggota NextHop dalam struktur MIB_IPFORWARD_ROW2 yang ditunjukkan oleh parameter Baris harus diinisialisasi ke alamat dan keluarga IPv4 atau IPv6 yang valid. Selain itu, setidaknya salah satu anggota berikut dalam struktur MIB_IPFORWARD_ROW2 yang menunjuk ke parameter Baris 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 tempat menambahkan entri rute IP. 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 Baris 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 CreateIpForwardEntry2 dipanggil. Anggota ini diatur oleh tumpukan jaringan dan tidak dapat diatur menggunakan fungsi CreateIpForwardEntry2 .

Fungsi CreateIpForwardEntry2 akan gagal jika anggota DestinationPrefix dan NextHopdari MIB_IPFORWARD_ROW2 yang ditunjukkan oleh parameter Baris adalah duplikat entri rute IP yang ada pada antarmuka yang ditentukan dalam anggota InterfaceLuid atau InterfaceIndex .

Fungsi CreateIpForwardEntry2 hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika CreateIpForwardEntry2 dipanggil oleh pengguna yang bukan anggota grup Administrator, panggilan fungsi akan gagal dan ERROR_ACCESS_DENIED dikembalikan. Fungsi ini 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