RtmAddNextHop function (rtmv2.h)
The RtmAddNextHop function adds a new next-hop entry or updates an existing next-hop entry to a client's next-hop list. If a next hop already exists, the routing table manager returns a handle to the next hop. This handle can then be used to specify a next hop to a destination when adding or updating a route.
Syntax
DWORD RtmAddNextHop(
[in] RTM_ENTITY_HANDLE RtmRegHandle,
[in] PRTM_NEXTHOP_INFO NextHopInfo,
[in, out] PRTM_NEXTHOP_HANDLE NextHopHandle,
[out] PRTM_NEXTHOP_CHANGE_FLAGS ChangeFlags
);
Parameters
[in] RtmRegHandle
Handle to the client obtained from a previous call to RtmRegisterEntity.
[in] NextHopInfo
Pointer to a structure that contains information identifying the next hop to add or update. The NextHopOwner and State members are ignored; these members are set by the routing table manager. The Flags member can be one of the following values.
[in, out] NextHopHandle
If the client has a handle (client is updating a next hop): On input, NextHopHandle is a pointer to the next-hop handle. On output, NextHopHandle is unchanged.
If the client does not have a handle and a handle must be returned (client is adding or updating a next hop): On input, NextHopHandle is a pointer to NULL. On output, NextHopHandle receives a pointer to the next-hop handle. The values in NextHopInfo are used to identify the next hop to update.
If a handle does not need to be returned (client is adding or updating a next hop): On input, NextHopHandle is NULL. The values in NextHopInfo are used to identify the next hop to update.
[out] ChangeFlags
On input, ChangeFlags is a pointer to an RTM_NEXTHOP_CHANGE_FLAGS data type.
On output, ChangeFlags receives a flag indicating whether a next hop was added or updated. If ChangeFlags is zero, a next hop was updated; if ChangeFlags is RTM_NEXTHOP_CHANGE_NEW, a next hop was added.
Return value
If the function succeeds, the return value is NO_ERROR.
If the function fails, the return value is one of the following error codes.
| Value | Meaning |
|---|---|
|
The calling client does not own this next hop. |
|
There is not enough memory to complete this operation. |
Remarks
If NextHopHandle points to a non-NULL handle, the next hop specified by the handle is updated. Otherwise, a search is made for the address specified by NextHopInfo. If a next hop is found, it is updated. If no match is found, a new next hop is added.
If a handle was returned, release the handle when it is no longer required by calling RtmReleaseNextHops.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | None supported |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | rtmv2.h |
| Library | Rtm.lib |
| DLL | Rtm.dll |