RtmAddRoute
[This is preliminary documentation and subject to change.]
The RtmAddRoute function adds a route entry, or updates an existing route entry.
DWORD RtmAddRoute(
HANDLE ClientHandle, // handle that identifies the client
PVOID Route, // pointer to new route structure
DWORD TimeToLive, // how long to keep the route
DWORD Flags, // best route change status
PVOID CurBestRoute, // pointer to new best route
PVOID PrevBestRoute // pointer to previous best route
);
Parameters
-
ClientHandle
-
A handle that identifies the client and therefore the routing protocol of the added or updated route. Obtain this handle by calling RtmRegisterClient.
-
Route
-
The address of a protocol-family-specific structure containing the new orupdated route. The following fields will be used by the RTM to update the routing table:
-
RR_Network
-
The destination network number.
-
RR_InterfaceID
-
The index of the interface through which the route was received.
-
RR_NextHopAddress
-
The address of the next hop router.
-
RR_FamilySpecificData
-
Data specific to the protocol family. Although the data is transparent to the RTM, it is considered when comparing routes to determine if route information has changed. The data is also used to set metric values that are independent of the routing protocol. Consequently, it's used to determine the best route for the destination network.
-
RR_ProtocolSpecificData
-
Data specific to the routing protocol that supplied the route.
-
RR_TimeStamp
-
The RTM sets this field with the current system time.
-
TimeToLive
-
The number of seconds the specified route should be kept in the routing table. If this parameter is set to INFINITE, the route is kept until explicitly deleted. The current limit for TimeToLive is 2147483 sec (24+ days).
-
Flags
-
The address of a DWORD variable. The value of this variable is set by the RTM. The value indicates the type of the change, and what information was returned in the provided buffers. This parameter will be one of the following.
Flags |
Values |
RTM_NO_CHANGE |
The addition or update either did not change any of the significant route parameters, or the route entry affected is not the best route among the entries for the destination network. |
RTM_ROUTE_ADDED |
The route added for the first for the destination network. The CurBestRoute parameter points to the information for the added route. |
RTM_ROUTE_CHANGED |
At least one of the significant parameters was changed for the best route to the destination network. The significant parameters are:
Protocol ID
Interface Index
Next Hop Address
Protocol Family Specific Data
(including route metrics)
|
The PrevBestRoute parameter points to the route information as it was before the change. The CurBestRoute parameter points to the current (that is, after-change) route information.
-
CurBestRoute
-
The address of a structure to receive the current best route information (if any). The type of the structure is specific to the protocol family (for example, IP or IPX).
This parameter is optional. If the caller specifies NULL for this parameter, the current best route information is not returned.
-
PrevBestRoute
-
The address of a structure to receive the previous best route information (if any). The type of the structure is specific to the protocol family (for example, IP or IPX).
This parameter is optional. If the caller specifies NULL for this parameter the previous best route information is not returned.
Return Value
-
NO_ERROR
-
The route was added/updated successfully.
-
ERROR_INVALID_HANDLE
-
The client handle parameter is not a valid RTM handle.
-
ERROR_INVALID_PARAMETER
-
The route structure contains an invalid parameter.
-
ERROR_NO_SYSTEM_RESOURCES
-
Insufficient resources to carry out the operation.
-
ERROR_NOT_ENOUGH_MEMORY
-
Insufficient memory to allocate the route entry.
Remarks
The function generates a route change message if the best route to a destination network has changed as the result of this operation. However, the route change message is not sent to the client that makes this call. Instead, relevant information is returned by this function directly to that client through the Flags, CurBestRoute, and PrevBestRoute parameters.
QuickInfo
Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rtm.h.
Import Library: Link with rtm.lib.
See Also
RtmDeleteRoute, RtmDequeueRouteChangeMessage