Share via

NotifyRouteChange (Compact 2013)

  • Article

3/26/2014

This function causes a notification to be sent to the caller when a change occurs in the IP routing table.

Syntax

DWORD NotifyRouteChange(
  PHANDLE Handle, 
  LPOVERLAPPED overlapped 
);

Parameters

  • Handle
    [in] A pointer to a HANDLE variable that receives a handle to use in asynchronous notification.
  • overlapped
    [in] A pointer to an OVERLAPPED structure that notifies the caller of any changes in the routing table.

Return Value

If the function succeeds, the return value is NO_ERROR if the caller specifies NULL for the Handle and overlapped parameters. If the caller specifies non-NULL parameters, the return value for success is ERROR_IO_PENDING. If the function fails, use FormatMessage to obtain the message string for the returned error.

Return code

Description

ERROR_CANCELLED

The context is being deregistered, so the call was canceled immediately.

ERROR_INVALID_PARAMETER

An invalid parameter was passed. This error is returned if the both the Handle and overlapped parameters are not NULL. However, the memory specified by the input parameters cannot be written by the calling process. This error is also returned if the client already has made a change notification request, so this duplicate request will fail.

ERROR_NOT_ENOUGH_MEMORY

There was insufficient memory available to complete the operation.

ERROR_NOT_SUPPORTED

This error is returned on versions of Windows where this function is not supported.

Remarks

The NotifyRouteChange function may be called in two ways:

  • Synchronous method
  • Asynchronous method

If the caller specifies NULL for the Handle and overlapped parameters, the call to NotifyRouteChange is synchronous and will block until an IPv4 routing table change occurs. In this case if a change occurs, the NotifyRouteChange function completes to indicate that a change has occurred.

If the NotifyRouteChange function is called synchronously, a notification will be sent on the next IPv4 routing change until the application terminates.

If the caller specifies a handle variable and an OVERLAPPED structure, the caller can use the returned handle with the OVERLAPPED structure to receive asynchronous notification of IPv4 routing table changes. See the following topics for information about how to use the handle and OVERLAPPED structure to receive notifications:

  • Synchronization and Overlapped Input and Output
  • GetQueuedCompletionStatus
  • I/O Completion Ports

If the application receives a notification and requires notification for the next change, the NotifyRouteChange function must be called again.

The CancelIPChangeNotify function cancels notification of IP address and route changes previously requested with successful calls to the NotifyAddrChange or NotifyRouteChange functions.

As soon as an application has been notified of a change, the application can then call the GetIpForwardTable or GetIpForwardTable2 function to retrieve the IPv4 routing table to determine what has changed. If the application is notified and requires notification for the next change, the NotifyRouteChange function must be called again.

If the NotifyRouteChange function is called asynchronously, a notification will be sent on the next IPv4 route change until either the application cancels the notification by calling the CancelIPChangeNotify function or the application terminates. If the application terminates, the system will automatically cancel the registration for the notification. It is still recommended that an application explicitly cancel any notification before it terminates.

Any registration for a notification does not persist across a system shut down or restart.

Requirements

Header

iphlpapi.h

Library

Iphlpapi.lib

See Also

Reference

IP Helper Functions
CancelIPChangeNotify
GetIpForwardTable
GetIpForwardTable2
NotifyAddrChange

Other Resources

IP Helper