Managing Routing
A version of this page is also available for
4/8/2010
IP Helper provides the functionality to manage network routing. Use the following functions to manage the IP routing table, and to obtain other routing information.
You can manipulate specific entries in the IP routing table. Use the CreateIpForwardEntry function to add a new routing table entry. Use the DeleteIpForwardEntry function to remove an existing entry. The SetIpForwardEntry function modifies an existing entry. You can retrieve the contents of the IP routing table by making a call to the GetIpForwardTable function.
You can also use the router management capabilities of IP Helper to retrieve information about how datagrams are routed over the network. The GetBestRoute function retrieves the best route to a specified destination address. The GetBestInterface function retrieves the index of the interface used by the best route to a specified destination address. Lastly, the GetRTTAndHopCount function retrieves the round-trip time (RTT) and number of hops to a specified destination address.
The following table describes each CreateIpForwardEntry variable and MIB_IPFORWARDROW member.
| Value | Description |
|---|---|
pRoute |
Pointer to a MIB_IPFORWARDROW structure that specifies the information for the new route. The caller must specify values for all members of this structure. The caller must specify PROTO_IP_NETMGMT for the dwForwardProto member of MIB_IPFORWARDROW. |
MIB_IPFORWARDROW (All fields are read-write, and can be changed by the API user with the SetIpForwardEntry function) |
dwForwardDest > [!NOTE] > The IP address of the destination host.dwForwardMask > [!NOTE] > The subnet mask of the destination host.dwForwardPolicy > [!NOTE] > Specifies the set of conditions that would cause the selection of a multi-path route. This member is typically in IP TOS format. For more information, see RFC 1354. This is not supported in Windows Embedded CE.dwForwardNextHop > [!NOTE] > Specifies the IP address of the next hop in the route.dwForwardIfIndex > [!NOTE] > Specifies the index of the interface for this route.dwForwardType > [!NOTE] > Specifies the route type as defined in RFC 1354. The following list shows the possible values for this member: > [!NOTE] > MIB_IPROUTE_TYPE_INDIRECT: The next hop is not the final destination (remote route). > [!NOTE] > MIB_IPROUTE_TYPE_DIRECT: The next hop is the final destination (local route). > [!NOTE] > MIB_IPROUTE_TYPE_INVALID: The route is valid. > [!NOTE] > MIB_IPROUTE_TYPE_OTHER: Other. > [!NOTE] > These values are declared in Iprtrmib.h.dwForwardProto > [!NOTE] > Specifies the protocol that generated the route. Possible protocols are declared in Iprtrmib.hdwForwardAge > [!NOTE] > Specifies the age of the route in seconds.dwForwardNextHopAS > [!NOTE] > Specifies the autonomous system number of the next hop. The autonomous system number is a way to identify an entire network (usually under a single administration), using the same routing protocol. This is not supported in Windows Embedded CE.dwForwardMetric1 > [!NOTE] > Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354. The first Metric is the only one currently used in Windows Embedded CE.dwForwardMetric2 > [!NOTE] > Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354. This Metric is unused in Windows Embedded CE, and is set to MIB_IPROUTE_METRIC_UNUSED.dwForwardMetric3 > [!NOTE] > Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354. This Metric is unused in Windows Embedded CE, and is set to MIB_IPROUTE_METRIC_UNUSED.dwForwardMetric4 > [!NOTE] > Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354. This Metric is unused in Windows Embedded CE, and is set to MIB_IPROUTE_METRIC_UNUSED.dwForwardMetric5 > [!NOTE] > Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354. This Metric is unused in Windows Embedded CE, and is set to MIB_IPROUTE_METRIC_UNUSED. |
Note
An example that shows how to set a routing-protocol-specific metric value is included within this document. See the code sample titled Setting ForwardMetric Values.
The following table describes each DeleteIpForwardEntry variable.
| Value | Description |
|---|---|
pRoute |
Pointer to a MIB_FORWARDROW structure (see the CreateIpForwardEntry description above). This structure specifies information that identifies the route to delete. The caller must specify values for the dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop, and dwForwardPolicy members of the structure. |
The following table describes each SetIpForwardEntry variable.
| Value | Description |
|---|---|
pRoute |
Pointer to a MIB_FORWARDROW structure (see the CreateIpForwardEntry description above). This structure specifies information that identifies the route to delete. The caller must specify values for the dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop, and dwForwardPolicy members of the structure. |
The following table describes each GetIpForwardTable variable.
| Value | Description |
|---|---|
pIpForwardTable |
Pointer to a buffer that, on successful return, contains the IP routing table as a MIB_IPFORWARDTABLE structure. |
pdwSize |
Specifies the size of the buffer pointed to by the pIpForwardTable parameter. If the buffer is not large enough to hold the returned routing table, the function sets this parameter equal to the required buffer size. |
bOrder |
Specifies whether the returned table should be sorted. If this parameter is TRUE, the table is sorted in this order:
|
MIB_IPFORWARDTABLE (The table itself is read-only, but the entries can be changed using SetIpForwardEntry) |
dwNumEntries > [!NOTE] > Specifies the number of route entries in the table.table[ANY_SIZE] > [!NOTE] > Pointer to a table of route entries implemented as an array of MIB_IPFORWARDROW structures. (See the CreateIpForwardEntry description above). |
The following table describes each GetBestRoute variable.
| Value | Description |
|---|---|
dwDestAddr |
Specifies the destination IP address for which to obtain the best route. |
dwSourceAddr |
Specifies a source IP address. This IP address corresponds to an interface on the local computer. If multiple best routes to the destination address exist, the function selects the route that uses this interface. This parameter is optional. The caller may specify zero for this parameter. |
pBestRoute |
Pointer to a MIB_IPFORWARDROW structure (See the CreateIpForwardEntry description above). On successful return, this structure contains the best route for the IP address specified by dwDestAddr. |
The following table describes each GetBestInterface variable.
| Value | Description |
|---|---|
dwDestAddr |
Specifies the destination IP address for which to retrieve the interface that has the best route. |
pdwBestIfIndex |
Pointer to a DWORD variable. On successful return, this variable contains the index of the interface that has the best route to the address specified by the dwDestAddr parameter. |
The following table describes each GetRTTAndHopCount variable.
| Value | Description |
|---|---|
DestIpAddress |
Specifies the IP address of the destination for which to determine the RTT and hop count. |
HopCount |
Pointer to a ULONG variable. On successful return, this variable contains the hop count to the destination specified by the DestIpAddress parameter. |
MaxHops |
Specifies the maximum number of hops to search for the destination. If the number of hops to the destination exceeds this number, the function terminates the search and returns FALSE. |
RTT |
Round-trip time in milliseconds to the destination specified by DestIpAddress. |