NotifyStableUnicastIpAddressTable (Compact 2013)

3/26/2014

This function retrieves the stable unicast IP address table on a local device.

Syntax

NETIOAPI_API NotifyStableUnicastIpAddressTable(
  __in     ADDRESS_FAMILY  Family,
  __inout  PMIB_UNICASTIPADDRESS_TABLE* Table,
  __in     PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  __in     PVOID CallerContext,
  __inout  HANDLE* NotificationHandle
);

Parameters

• Family
  The address family to retrieve.

  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.

  The header file organization 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, the function retrieves the stable unicast IP address table that contains both IPv4 and IPv6 entries.
  AF_INET 2	The Internet Protocol version 4 (IPv4) address family. When this parameter is specified, the function retrieves the stable unicast IP address table that contains only IPv4 entries.
  AF_INET6 23	The Internet Protocol version 6 (IPv6) address family. When this parameter is specified, the function retrieves the stable unicast IP address table that contains only IPv6 entries.

• Table
  A pointer to a MIB_UNICASTIPADDRESS_TABLE structure. When NotifyStableUnicastIpAddressTable is successful, this parameter returns the stable unicast IP address table on the local device.

  When NotifyStableUnicastIpAddressTable returns ERROR_IO_PENDING that indicates that the I/O request is pending, the stable unicast IP address table is returned to the function in the CallerCallback parameter.

• CallerCallback
  A pointer to the function to call with the stable unicast IP address table. This function will be invoked if NotifyStableUnicastIpAddressTable returns ERROR_IO_PENDING, indicating that the I/O request is pending.

• CallerContext
  A user context passed to the callback function specified in the CallerCallback parameter when the stable unicast IP address table is available.

• NotificationHandle
  A pointer used to return a handle that can be used to cancel the request to retrieve the stable unicast IP address table. This parameter is returned if the return value from NotifyStableUnicastIpAddressTable is ERROR_IO_PENDING that indicates that the I/O request is pending.

Return Value

If the function succeeds immediately, the return value is NO_ERROR and the stable unicast IP table is returned in the Table parameter.

If the I/O request is pending, the function returns ERROR_IO_PENDING and the function pointed to by the CallerCallback parameter is called when the I/O request has completed with the stable unicast IP address table.

If the function fails, the return value is one of the following error codes.

Remarks

All unicast IP addresses except dial-on-demand addresses are considered stable only if they are in the preferred state. For a usual unicast IP address entry, this would correspond to a DadState member of the MIB_UNICASTIPADDRESS_ROW for the IP address set to IpDadStatePreferred. Every dial-on-demand address defines its own stability metric.

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

When NotifyStableUnicastIpAddressTable is successful and returns NO_ERROR, the Table parameter returns the stable unicast IP address table on the local device.

When NotifyStableUnicastIpAddressTable returns ERROR_IO_PENDING that indicates that the I/O request is pending, the stable unicast IP address table is returned to the function in the CallerCallback parameter.

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

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

To deregister for change notifications, call the CancelMibChangeNotify2 function passing the NotificationHandle parameter returned by NotifyStableUnicastIpAddressTable.

As soon as the NotifyStableUnicastIpAddressTable 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 any 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
CreateUnicastIpAddressEntry
DeleteUnicastIpAddressEntry
GetUnicastIpAddressEntry
GetUnicastIpAddressTable
InitializeUnicastIpAddressEntry
MIB_NOTIFICATION_TYPE
MIB_UNICASTIPADDRESS_ROW
MIB_UNICASTIPADDRESS_TABLE
NotifyUnicastIpAddressChange
SetUnicastIpAddressEntry

Other Resources

IP Helper