Fungsi SetIpForwardEntry (iphlpapi.h)

Fungsi SetIpForwardEntry memodifikasi rute yang ada di tabel perutean IPv4 komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE DWORD SetIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Parameter

[in] pRoute

Penunjuk ke struktur MIB_IPFORWARDROW yang menentukan informasi baru untuk rute yang ada. Pemanggil harus menentukan MIB_IPPROTO_NETMGMT untuk anggota dwForwardProto dari struktur ini. Pemanggil juga harus menentukan nilai untuk anggota dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop, dan dwForwardPolicy dari struktur.

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_ACCESS_DENIED	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).
ERROR_FILE_NOT_FOUND	Sistem tidak dapat menemukan file yang ditentukan. Kesalahan ini dikembalikan pada Windows Vista dan kemudian jika antarmuka jaringan yang ditentukan oleh anggota dwForwardIfIndex dari struktur MIB_IPFORWARDROW yang diarahkan oleh parameter pRoute tidak dapat ditemukan.
ERROR_INVALID_PARAMETER	Parameter pRouteadalah NULL, atau SetIpForwardEntry tidak dapat membaca dari memori yang diarahkan oleh pRoute, atau salah satu anggota struktur MIB_IPFORWARDROW tidak valid.
ERROR_NOT_FOUND	Elemen tidak ditemukan. Kesalahan dikembalikan pada Windows Vista dan kemudian ketika fungsi DeleteIpForwardEntry dan kemudian fungsi SetIpForwardEntry dipanggil untuk entri tabel rute IPv4 yang sama.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Nilai ini dikembalikan jika transportasi IPv4 tidak dikonfigurasi pada komputer lokal. Kesalahan ini juga dikembalikan pada Windows Server 2003 dan sebelumnya jika tidak ada tumpukan TCP/IP yang dikonfigurasi di komputer lokal.
Lainnya	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 , SetIpForwardEntry 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, fungsi SetIpForwardEntry hanya berfungsi pada antarmuka dengan sub-antarmuka tunggal (di mana LUID antarmuka dan SUBINTERFACE LUID sama). Anggota dwForwardIfIndex dari struktur MIB_IPFORWARDROW menentukan antarmuka.

Anggota dwForwardAge struktur MIB_IPFORWARDROW yang diarahkan oleh parameter rute saat ini tidak digunakan oleh SetIpForwardEntry. Anggota dwForwardAge hanya digunakan jika Perutean dan Layanan Akses Jarak Jauh (RRAS)berjalan, lalu hanya untuk rute jenis MIB_IPPROTO_NETMGMT seperti yang didefinisikan pada halaman referensi Pengidentifikasi Protokol . Ketika dwForwardAge diatur ke INFINITE, rute tidak akan dihapus berdasarkan batas waktu

Nilai. Nilai lain untuk dwForwardAge menentukan jumlah detik hingga tumpukan TCP/IP akan menghapus rute dari tabel perutean jaringan.

Rute yang dimodifikasi oleh SetIpForwardEntry akan secara otomatis memiliki nilai default untuk dwForwardAge of INFINITE.

Sejumlah anggota struktur MIB_IPFORWARDROW yang diarahkan oleh parameter rute saat ini tidak digunakan oleh SetIpForwardEntry. Anggota ini termasuk dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4, dan dwForwardMetric5.

Untuk membuat rute baru dalam tabel perutean IP, gunakan fungsi CreateIpForwardEntry . Untuk mengambil tabel perutean IP, panggil fungsi GetIpForwardTable .

Pada Windows Vista dan yang lebih baru, fungsi SetIpForwardEntry hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika SetIpForwardEntry 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 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.

Catatan Pada Windows NT 4.0 dan Windows 2000 dan yang lebih baru, fungsi ini menjalankan operasi istimewa. Agar fungsi ini berhasil dijalankan, pemanggil harus masuk sebagai anggota grup Administrator atau grup NetworkConfigurationOperators.

Contoh

Contoh berikut menunjukkan cara mengubah gateway default ke NewGateway. Cukup memanggil GetIpForwardTable, mengubah gateway dan kemudian 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.

Catatan Menjalankan kode ini akan mengubah tabel perutean IP Anda dan kemungkinan akan menyebabkan aktivitas jaringan gagal.

Windows Vista dan yang lebih baru: Ketika fungsi DeleteIpForwardEntry lalu fungsi SetIpForwardEntry dipanggil untuk entri tabel rute yang sama pada Windows Vista dan yang lebih baru, ERROR_NOT_FOUND dikembalikan. Cara yang tepat untuk mereplikasi contoh ini pada Windows Vista dan yang lebih baru adalah dengan menggunakan fungsi CreateIpForwardEntry untuk membuat entri tabel rute baru lalu menghapus entri tabel rute lama dengan memanggil fungsi DeleteIpForwardEntry .

#pragma comment(lib, "IPHLPAPI.lib")

// #ifndef WIN32_LEAN_AND_MEAN
// #define WIN32_LEAN_AND_MEAN
// #endif

// #pragma warning(push)
// #pragma warning(disable: 4127)

// #include <windows.h>

#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
/* Note: could also use malloc() and free() */

int main()
{

    // Declare and initialize variables.

    /* variables used for SetIfForwardEntry */

    PMIB_IPFORWARDTABLE pIpForwardTable = NULL;
    PMIB_IPFORWARDROW pRow = NULL;
    DWORD dwSize = 0;
    BOOL bOrder = FALSE;
    DWORD dwStatus = 0;
    DWORD NewGateway = 0xDDBBCCAA;      // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
    DWORD 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
        pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize);
        if (pIpForwardTable == NULL) {
            printf("Unable to allocate memory for the IPFORWARDTALE\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 to 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 = SetIpForwardEntry(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);
}

Persyaratan

Persyaratan	Nilai
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

Lihat juga

Referensi Fungsi Pembantu IP

Halaman Mulai Pembantu IP

MIB_IPFORWARDROW

MIB_IPINTERFACE_ROW

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2023-08-24