RtmDequeueRouteChangeMessage

[This is preliminary documentation and subject to change.]

The RtmDequeueRouteChangeMessage function returns the next route-change message in the queue associated with the specified client.

DWORD RtmDequeueRouteChangeMessage(
  HANDLE ClientHandle,      // handle that identifies the client
  DWORD Flags,              // type of change message
  PVOID CurBestRoute,       // the new best route
  PVOID PrevBestRoute       // the previous best route
);
 

Parameters

ClientHandle

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

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 message, and what information was returned in the provided buffers. This parameter will be one of the following.

Flags	Values
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 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 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 Values

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 RTM 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 RTM 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

Insufficient resources to carry out the operation.

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

RtmRegisterClient