rtmaddroute.md

title	description	ms.assetid	keywords	topic_type	api_name	api_location	api_type	ms.topic	ms.date
RtmAddRoute function (Rtm.h)	The RtmAddRoute function adds a route entry or updates an existing route entry.	09a9b57d-f10b-40b7-a3c1-2e0613f29431	RtmAddRoute function RAS	apiref	RtmAddRoute	Rtm.dll	DllExport	reference	05/31/2018

RtmAddRoute function

[This API has been superseded by the Routing Table Manager Version 2 API and will not be available beyond Windows Server 2003. Applications should use the Routing Table Manager Version 2 API.]

The RtmAddRoute function adds a route entry or updates an existing route entry.

Syntax

DWORD RtmAddRoute(
  _In_  HANDLE ClientHandle,
  _In_  PVOID  Route,
  _In_  DWORD  TimeToLive,
  _Out_ DWORD  Flags,
  _Out_ PVOID  CurBestRoute,
  _Out_ PVOID  PrevBestRoute
);

Parameters

ClientHandle [in]

Handle that identifies the client, and therefore the routing protocol, that added or updated the route. Obtain this handle by calling RtmRegisterClient.

Route [in]

Pointer to a protocol-family-specific structure that specifies the new or updated route. The following fields are used by the routing table manager to update the routing table:

Value	Meaning
RR_Network	Specifies the destination network number.
RR_InterfaceID	Specifies the index of the interface through which the route was received.
RR_NextHopAddress	Specifies the address of the next-hop router.
RR_FamilySpecificData	Specifies data that is specific to the protocol family. Although the data is transparent to the routing table manager, 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, this data is used to determine the best route for the destination network.
RR_ProtocolSpecificData	Specifies data which is specific to the routing protocol that supplied the route.
RR_TimeStamp	Specifies the current system time. This field is set by the routing table manager.

TimeToLive [in]

Specifies 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 it is explicitly deleted. The current limit for TimeToLive is 2147483 sec (24+ days).

Flags [out]

Pointer to a DWORD variable. The value of this variable is set by the routing table manager. The value indicates the type of the change, and what information was returned in the provided buffers. This parameter is one of the following.

Flags	Meaning
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 was added 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 identifier 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 [out]

Pointer to a structure that receives 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 [out]

Pointer to a structure that receives 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

The return value is one of the following codes.

Value	Description
NO_ERROR	The route was added or updated successfully.
ERROR_INVALID_HANDLE	The client handle parameter is not a valid handle.
ERROR_INVALID_PARAMETER	The route structure contains an invalid parameter.
ERROR_NO_SYSTEM_RESOURCES	There are insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY	There is 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.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows 2000 Server [desktop apps only]
End of server support	Windows Server 2003
Header	Rtm.h
Library	Rtm.lib
DLL	Rtm.dll

See also

Routing Table Manager Version 1 Reference

Routing Table Manager Version 1 Functions

RtmDeleteRoute

RtmDequeueRouteChangeMessage