SetIpForwardEntry Function

IP Helper API | SDK: Windows SDK | Header: iprtrmib.h | Library: Iphlpapi.lib

The SetIpForwardEntry function modifies an existing IP route entry in the IP routing table.

Syntax


BOOL SetIpForwardEntry(
  PMIB_IPFORWARDROW pRoute
);

Parameters

pRoute: A pointer to a MIB_IPFORWARDROW structure that contains information for the IP route entry to be modified.

Return Value

Returns TRUE if the function succeeds, or FALSE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The SetIpForwardEntry function is used to modify an existing IP route. To modify a route, you must first retrieve the existing route using the GetIpForwardEntry function, then modify the appropriate members of the MIB_IPFORWARDROW structure, and finally call SetIpForwardEntry with the modified structure.

The following members of the MIB_IPFORWARDROW structure must be set for the function to work:

dwForwardDest
dwForwardMask
dwForwardProto
dwForwardType
dwForwardIfIndex
dwForwardNextHopIPAddr

If you are setting an entry for a specific interface and next hop, ensure that the dwForwardIfIndex and dwForwardNextHopIPAddr members are correctly populated. If the next hop is the local machine, dwForwardNextHopIPAddr should be set to 0.0.0.0.

Note

Modifying IP routing tables requires administrative privileges.

Example

The following example demonstrates how to modify an IP route entry:


#include <windows.h>
#include <iprtrmib.h>
#include <iphlpapi.h>
#include <stdio.h>

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

int main() {
    MIB_IPFORWARDROW ipRoute;
    DWORD dwRetVal;

    // Initialize the structure
    ZeroMemory(&ipRoute, sizeof(MIB_IPFORWARDROW));

    // Specify the existing route to modify
    ipRoute.dwForwardDest = inet_addr("192.168.1.0");       // Destination network
    ipRoute.dwForwardMask = inet_addr("255.255.255.0");     // Subnet mask
    ipRoute.dwForwardProto = PROTO_IP;                     // Protocol (IP)
    ipRoute.dwForwardType = MIB_IPROUTE_TYPE_OTHER;        // Route type
    ipRoute.dwForwardIfIndex = 1;                          // Interface index (example)
    ipRoute.dwForwardNextHopIPAddr = inet_addr("192.168.1.1"); // Next hop IP address

    // You would typically call GetIpForwardEntry here first to retrieve the current entry
    // For demonstration, we are directly setting the values.

    // Modify the route metric (example)
    ipRoute.dwForwardMetric1 = 2; // Set metric to 2

    printf("Modifying IP route entry...\n");

    // Call SetIpForwardEntry to modify the route
    dwRetVal = SetIpForwardEntry(&ipRoute);

    if (dwRetVal == NO_ERROR) {
        printf("Successfully modified IP route entry.\n");
    } else {
        printf("Error: %lu\n", dwRetVal);
        if (dwRetVal == ERROR_FILE_NOT_FOUND) {
            printf("The specified route entry was not found.\n");
        } else if (dwRetVal == ERROR_ACCESS_DENIED) {
             printf("Administrative privileges required.\n");
        }
    }

    return 0;
}

Requirements

Minimum supported client: Windows XP
Minimum supported server: Windows Server 2003
Header: iprtrmib.h (include Iphlpapi.h)
Library: Iphlpapi.lib
DLL: Iphlpapi.dll

Windows API Reference