Fungsi CreateIpForwardEntry (iphlpapi.h)
Fungsi CreateIpForwardEntry membuat rute di tabel perutean IPv4 komputer lokal.
Sintaks
IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Parameter
[in] pRoute
Penunjuk ke struktur MIB_IPFORWARDROW yang menentukan informasi untuk rute baru. Pemanggil harus menentukan nilai untuk semua anggota struktur ini. Pemanggil harus menentukan MIB_IPPROTO_NETMGMT untuk anggota dwForwardProtodari MIB_IPFORWARDROW.
Menampilkan nilai
Fungsi mengembalikan NO_ERROR (nol) jika fungsi berhasil.
Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Akses ditolak. Kesalahan ini dikembalikan pada Windows Vista dan Windows Server 2008 dalam beberapa kondisi yang mencakup hal berikut: pengguna tidak memiliki hak administratif yang diperlukan pada komputer lokal atau aplikasi tidak berjalan dalam shell yang ditingkatkan sebagai Administrator bawaan (administrator RunAs). |
|
Parameter input tidak valid, tidak ada tindakan yang diambil. Kesalahan ini dikembalikan jika parameter pRoute adalah NULL, anggota dwForwardProtodari MIB_IPFORWARDROW tidak diatur ke MIB_IPPROTO_NETMGMT, anggota dwForwardMask dari struktur PMIB_IPFORWARDROW bukan subnet mask IPv4 yang valid, atau salah satu anggota lain dari struktur MIB_IPFORWARDROW tidak valid. |
|
Transportasi IPv4 tidak dikonfigurasi pada komputer lokal. |
|
Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan. |
Keterangan
Anggota dwForwardProto dari struktur MIB_IPFORWARDROW yang diarahkan oleh parameter rute harus diatur ke MIB_IPPROTO_NETMGMT jika tidak , CreateIpForwardEntry akan gagal. Pengidentifikasi protokol perutean digunakan untuk mengidentifikasi informasi rute untuk protokol perutean yang ditentukan. Misalnya, MIB_IPPROTO_NETMGMT digunakan untuk mengidentifikasi informasi rute untuk perutean IP yang diatur melalui manajemen jaringan seperti Dynamic Host Configuration Protocol (DHCP), Simple Network Management Protocol (SNMP), atau dengan panggilan ke fungsi CreateIpForwardEntry, DeleteIpForwardEntry, atau SetIpForwardEntry .
Pada Windows Vista dan Windows Server 2008, metrik rute yang ditentukan dalam anggota dwForwardMetric1 dari struktur MIB_IPFORWARDROW yang ditunjukkan oleh parameter pRoute mewakili kombinasi metrik rute yang ditambahkan ke metrik antarmuka yang ditentukan dalam anggota Metrik dari struktur MIB_IPINTERFACE_ROW antarmuka terkait. Jadi anggota dwForwardMetric1 dari struktur MIB_IPFORWARDROW harus sama dengan atau lebih besar dari anggota Metrik dari struktur MIB_IPINTERFACE_ROW terkait. Jika aplikasi ingin mengatur metrik rute ke 0, maka anggota dwForwardMetric1 dari struktur MIB_IPFORWARDROW harus diatur sama dengan nilai metrik antarmuka yang ditentukan dalam anggota Metrik dari struktur MIB_IPINTERFACE_ROW terkait. Aplikasi dapat mengambil metrik antarmuka dengan memanggil fungsi GetIpInterfaceEntry .
Pada Windows Vista dan Windows Server 2008, CreateIpForwardEntry hanya berfungsi pada antarmuka dengan satu sub-antarmuka (di mana LUID antarmuka dan SUBINTERFACE LUID sama). Anggota dwForwardIfIndex dari struktur MIB_IPFORWARDROW menentukan antarmuka.
Sejumlah anggota struktur MIB_IPFORWARDROW yang diarahkan oleh parameter rute saat ini tidak digunakan oleh CreateIpForwardEntry. Anggota ini termasuk dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4, dan dwForwardMetric5.
Rute baru yang dibuat oleh CreateIpForwardEntry akan secara otomatis memiliki nilai default untuk dwForwardAge of INFINITE.
Untuk mengubah rute yang ada dalam tabel perutean IPv4, gunakan fungsi SetIpForwardEntry . Untuk mengambil tabel perutean IPv4, panggil fungsi GetIpForwardTable .
Pada Windows Vista dan yang lebih baru, fungsi CreateIpForwardEntry hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika CreateIpForwardEntry dipanggil oleh pengguna yang bukan anggota grup Administrator, panggilan fungsi akan gagal dan ERROR_ACCESS_DENIED dikembalikan.
Fungsi CreateIpForwardEntry 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 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.
Contoh
Contoh berikut menunjukkan cara mengubah gateway default ke NewGateway. Cukup memanggil GetIpForwardTable, mengubah gateway, lalu memanggil SetIpForwardEntry tidak akan mengubah rute, melainkan hanya akan menambahkan yang baru. Jika karena alasan tertentu ada beberapa gateway default yang ada, kode ini akan menghapusnya. Perhatikan bahwa gateway baru harus layak; jika tidak, TCP/IP akan mengabaikan perubahan.
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>
#pragma comment(lib, "iphlpapi.lib")
int main()
{
// Declare and initialize variables
PMIB_IPFORWARDTABLE pIpForwardTable = NULL;
PMIB_IPFORWARDROW pRow = NULL;
DWORD dwSize = 0;
BOOL bOrder = FALSE;
DWORD dwStatus = 0;
DWORD NewGateway = 0xDDCCBBAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
unsigned int i;
// Find out how big our buffer needs to be.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
// Allocate the memory for the table
if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Now get the table.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
}
if (dwStatus != ERROR_SUCCESS) {
printf("getIpForwardTable failed.\n");
if (pIpForwardTable)
free(pIpForwardTable);
exit(1);
}
// Search for the row in the table we want. The default gateway has a destination
// of 0.0.0.0. Notice that we continue looking through the table, but copy only
// one row. This is so that if there happen to be multiple default gateways, we can
// be sure to delete them all.
for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
if (pIpForwardTable->table[i].dwForwardDest == 0) {
// We have found the default gateway.
if (!pRow) {
// Allocate some memory to store the row in; this is easier than filling
// in the row structure ourselves, and we can be sure we change only the
// gateway address.
pRow = (PMIB_IPFORWARDROW) malloc(sizeof (MIB_IPFORWARDROW));
if (!pRow) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Copy the row
memcpy(pRow, &(pIpForwardTable->table[i]),
sizeof (MIB_IPFORWARDROW));
}
// Delete the old default gateway entry.
dwStatus = DeleteIpForwardEntry(&(pIpForwardTable->table[i]));
if (dwStatus != ERROR_SUCCESS) {
printf("Could not delete old gateway\n");
exit(1);
}
}
}
// Set the nexthop field to our new gateway - all the other properties of the route will
// be the same as they were previously.
pRow->dwForwardNextHop = NewGateway;
// Create a new route entry for the default gateway.
dwStatus = CreateIpForwardEntry(pRow);
if (dwStatus == NO_ERROR)
printf("Gateway changed successfully\n");
else if (dwStatus == ERROR_INVALID_PARAMETER)
printf("Invalid parameter.\n");
else
printf("Error: %d\n", dwStatus);
// Free resources
if (pIpForwardTable)
free(pIpForwardTable);
if (pRow)
free(pRow);
exit(0);
}
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | iphlpapi.h |
| Pustaka | Iphlpapi.lib |
| DLL | Iphlpapi.dll |