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