Share via

NotifyIpInterfaceChange (Compact 2013)

  • Article

3/26/2014

This function registers to be notified for changes to all IP interfaces, IPv4 interfaces, or IPv6 interfaces on a local device.

Syntax

NETIOAPI_API NotifyIpInterfaceChange(
  __in     ADDRESS_FAMILY Family,
  __in     PIPINTERFACE_CHANGE_CALLBACK Callback,
  __in     PVOID CallerContext,
  __in     BOOLEAN InitialNotification,
  __inout  HANDLE* NotificationHandle
);

Parameters

  • Family
    The address family on which to register for change notifications.

    Possible values for the address family are listed in the Winsock2.h header file. Note that the values for the AF_ address family and PF_ protocol family constants are identical (for example, AF_INET and PF_INET), so either constant can be used.

    On the Windows SDK, the organization of header files has changed and possible values for this member are defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

    The values currently supported are AF_INET, AF_INET6, and AF_UNSPEC.

    Value

    Meaning

    AF_UNSPEC

    0

    The address family is unspecified. When this parameter is specified, this function registers for both IPv4 and IPv6 change notifications.

    AF_INET

    2

    The Internet Protocol version 4 (IPv4) address family. When this parameter is specified, this function register for only IPv4 change notifications.

    AF_INET6

    23

    The Internet Protocol version 6 (IPv6) address family. When this parameter is specified, this function registers for only IPv6 change notifications.
  • Callback
    A pointer to the function to call when a change occurs. This function will be invoked when an interface notification is received.
  • CallerContext
    A user context passed to the callback function specified in the Callback parameter when an interface notification is received.
  • InitialNotification
    A value that indicates whether the callback should be invoked immediately after registration for change notification is complete. This initial notification does not indicate a change occurred to an IP interface. The purpose of this parameter to provide confirmation that the callback is registered.
  • NotificationHandle
    A pointer used to return a handle that can be later used to deregister the change notification. On success, a notification handle is returned in this parameter. If an error occurs, NULL is returned.

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.

Error Code

Meaning

ERROR_INVALID_HANDLE

An internal error occurred where an invalid handle was encountered.

ERROR_INVALID_PARAMETER

An invalid parameter was passed to the function. This error is returned if the Family parameter was not either AF_INET, AF_INET6, or AF_UNSPEC.

ERROR_NOT_ENOUGH_MEMORY

There was insufficient memory.

Other

Use FormatMessage to obtain the message string for the returned error.

Remarks

The Family parameter must be set to either AF_INET, AF_INET6, or AF_UNSPEC.

The invocation of the callback function specified in the Callback parameter is serialized. The callback function should be defined as a function of type VOID. The parameters that are passed to the callback function include the following:

Parameter

Description

IN PVOID CallerContext

The CallerContext parameter that is passed to the NotifyIpInterfaceChange function when registering for notifications.

IN PMIB_IPINTERFACE_ROW Row OPTIONAL

A pointer to the MIB_IPINTERFACE_ROW entry for the interface that was changed. This parameter is a NULL pointer when the MIB_NOTIFICATION_TYPE value that is passed in the NotificationType parameter to the callback function is set to MibInitialNotification. This can only occur if the InitialNotification parameter that is passed to NotifyIpInterfaceChange was set to TRUE when registering for notifications.

IN MIB_NOTIFICATION_TYPE NotificationType

The notification type. This member can be one of the values from the MIB_NOTIFICATION_TYPE enumeration type that is defined in the Netioapi.h header file.

The callback function specified in the Callback parameter must be implemented in the same process as the application calling the NotifyIpInterfaceChange function. If the callback function is in a separate DLL, then the DLL should be loaded before calling the NotifyIpInterfaceChange function to register for change notifications.

To unregister for change notifications, call the CancelMibChangeNotify2 function passing the NotificationHandle parameter returned by NotifyIpInterfaceChange.

As soon as the NotifyIpInterfaceChange function is called to register for change notifications, these notifications will continue to be sent until the application deregisters for change notifications or the application terminates. If the application terminates, the system will automatically unregister any registration for change notifications. It is still recommended that an application explicitly unregister for change notifications before it terminates.

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

See Also

Reference

IP Helper Functions
CancelMibChangeNotify2
GetIfEntry2
GetIfStackTable
GetIfTable2
GetInvertedIfStackTable
GetIpInterfaceEntry
InitializeIpInterfaceEntry
MIB_IF_ROW2
MIB_IF_TABLE2
MIB_IPINTERFACE_ROW
MIB_NOTIFICATION_TYPE
SetIpInterfaceEntry

Other Resources

IP Helper