RtmDequeueRouteChangeMessage 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 RtmDequeueRouteChangeMessage function returns the next route-change message in the queue associated with the specified client.

Syntax

DWORD RtmDequeueRouteChangeMessage(
  _In_  HANDLE ClientHandle,
  _Out_ DWORD  Flags,
  _Out_ PVOID  CurBestRoute,
  _Out_ PVOID  PrevBestRoute
);

Parameters

ClientHandle [in]

Handle that identifies the client for which the operation is performed. Obtain this handle by calling RtmRegisterClient.

Flags [out]

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

Flags	Meaning
RTM_ROUTE_ADDED	The first route was added for a particular destination network. The CurBestRoute parameter points to the information for the added route.
RTM_ROUTE_DELETED	The only route available for a particular destination network was deleted. The PrevBestRoute parameter points to the information for the deleted route.
RTM_ROUTE_CHANGED	At least one of the significant parameters was changed for a best route to a particular 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 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	This message was the last message in the client's queue. The event object is reset.
ERROR_INVALID_HANDLE	The ClientHandle parameter is not a valid handle, or at registration the client did not provide an event object for change message notification (see RtmRegisterClient).
ERROR_MORE_MESSAGES	The client's queue contains additional messages. The client should call RtmDequeueRouteChangeMessage again as soon as possible to allow the routing table manager to free the resources associated with the pending messages.
ERROR_NO_MESSAGES	The client's queue contains no messages; the call was unsolicited. The event is reset.
ERROR_NO_SYSTEM_RESOURCES	There are insufficient resources to carry out the operation.

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

RtmRegisterClient