NotifyUnicastIpAddressChange (Compact 2013)

3/26/2014

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

Syntax

NETIOAPI_API
  NotifyUnicastIpAddressChange(
    IN ADDRESS_FAMILY  Family,
    IN PUNICAST_IPADDRESS_CHANGE_CALLBACK  Callback,
    IN PVOID  CallerContext,
    IN BOOLEAN  InitialNotification,
    IN OUT HANDLE*  NotificationHandle
    );

Parameters

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

  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 you can use either constant.

  On later versions of the Windows operating systems, possible values for the Family parameter are defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Netioapi.h and you should never use Ws2def.h directly.

  The following values are currently supported for the address family:

  Value	Meaning
  AF_UNSPEC	The address family is unspecified. When this value is specified, the function registers the driver only for unicast IPv4 address change notifications.
  AF_INET	The IPv4 address family. When this value is specified, the function registers the driver only for unicast IPv6 address change notifications.
  AF_INET6	The IPv6 address family. When this value is specified, the function registers the driver for both unicast IPv4 and IPv6 address change notifications.

• Callback
  A pointer to the function to call when a change occurs. This function is called when a unicast IP address notification is received.

• CallerContext
  A user context that is passed to the callback function that is specified in the Callback parameter when an interface notification is received.

• InitialNotification
  A value that indicates whether the callback should be called immediately after registration for change notification is is completed. This initial notification does not indicate that a change occurred to a unicast IP address. This parameter provides confirmation that the callback is registered.

• NotificationHandle
  A pointer that is used to return a handle that your driver can later use to deregister the driver change notification. On success, a notification handle is returned in this parameter. If an error occurs, NULL is returned.

Return Value

NotifyUnicastIpAddressChange returns STATUS_SUCCESS if the function succeeds.

If the function fails, NotifyUnicastIpAddressChange returns one of the following error codes:

Error Code	Meaning
ERROR_INVALID_HANDLE	An internal error occurred where an invalid handle was encountered.
STATUS_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.
STATUS_NOT_ENOUGH_MEMORY	There was insufficient memory.
Other	Use the FormatMessage function to obtain the message string for the returned error.

Remarks

Your driver must set the Family parameter to either AF_INET, AF_INET6, or AF_UNSPEC.

The invocation of the callback function that is 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 NotifyUnicastIpAddressChange function when it is registering the driver for change notifications.
IN PMIB_UNICASTIPADDRESS_ROW Row OPTIONAL	A pointer to the MIB_UNICASTIPADDRESS_ROW entry for the unicast IP address 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 situation can occur only if the InitialNotification parameter that is passed to NotifyUnicastIpAddressChange was set to TRUE when registering the driver for change notifications.
IN MIB_NOTIFICATION_TYPE NotificationType	The notification type. This member can be one of the values from the MIB_NOTIFICATION_TYPE enumeration type.

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

To deregister the driver for change notifications, call the CancelMibChangeNotify2 (NETIOAPI) function, passing the NotificationHandle parameter that NotifyUnicastIpAddressChange returns.

As soon as the NotifyUnicastIpAddressChange 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 deregister any registration for change notifications. It is still recommended that an application explicitly deregister for change notifications before it terminates.

Any registration for change notifications does not persist if the system is shut down or restarted.

See Also

Reference

IP Helper Functions
CancelMibChangeNotify2 (NETIOAPI)
CreateUnicastIpAddressEntry (NETIOAPI)
DeleteUnicastIpAddressEntry (NETIOAPI)
GetUnicastIpAddressEntry (NETIOAPI)
GetUnicastIpAddressTable (NETIOAPI)
InitializeUnicastIpAddressEntry (NETIOAPI)
MIB_NOTIFICATION_TYPE
MIB_UNICASTIPADDRESS_ROW
MIB_UNICASTIPADDRESS_TABLE
NotifyStableUnicastIpAddressTable (NETIOAPI)
SetUnicastIpAddressEntry (NETIOAPI)