NotifyStableUnicastIpAddressTable function

The NotifyStableUnicastIpAddressTable function retrieves the stable unicast IP address table on a local computer.

Syntax


NETIOAPI_API NotifyStableUnicastIpAddressTable(
  _In_    ADDRESS_FAMILY                           Family,
  _Out_   PMIB_UNICASTIPADDRESS_TABLE              *Table,
  _In_    PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  _In_    PVOID                                    CallerContext,
  _Inout_ HANDLE                                   *NotificationHandle
);

Parameters

Family [in]

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

On Windows Vista and 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:

AF_INET

The IPv4 address family. When this value is specified, the function retrieves the stable unicast IP address table that contains only IPv4 entries.

AF_INET6

The IPv6 address family. When this value is specified, the function retrieves the stable unicast IP address table that contains only IPv6 entries.

AF_UNSPEC

The address family is unspecified. When this value is specified, the function retrieves the stable unicast IP address table that contains both IPv4 and IPv6 entries.

Table [out]

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

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

CallerCallback [in]

A pointer to the function to call with the stable unicast IP address table. This function is called if NotifyStableUnicastIpAddressTable returns ERROR_IO_PENDING, which indicates that the I/O request is pending.

CallerContext [in]

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

NotificationHandle [in, out]

A pointer that is used to return a handle that your driver can use 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, which indicates that the I/O request is pending.

Return value

NotifyStableUnicastIpAddressTable returns STATUS_SUCCESS and the stable unicast IP table is returned in the Table parameter if the function succeeds immediately.

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

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

Return codeDescription
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 Table parameter was a NULL pointer, the NotificationHandle parameter was a NULL pointer, or 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

All unicast IP addresses, except dial-on-demand addresses, are considered stable only if they are in the preferred state. For a normal unicast IP address entry, this state would correspond to a DadState member of the MIB_UNICASTIPADDRESS_ROW for the IP address that is set to IpDadStatePreferred. Every dial-on-demand address defines its own stability metric. Currently the only dial-on-demand address that the NotifyStableUnicastIpAddressTable function considers is the unicast IP address that the Teredo client uses on the local computer.

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

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

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

If the unicast IP address that Teredo uses is available on the local computer but not in the stable (qualified) state, NotifyStableUnicastIpAddressTable returns ERROR_IO_PENDING and the stable unicast IP address table is eventually returned by calling the function in the CallerCallback parameter. If the Teredo address is not available or is in the stable state and the other unicast IP addresses are in a stable state, the function in the CallerCallback parameter is never called.

The callback function that is 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.

ParameterDescription

IN PVOID CallerContext

The CallerContext parameter that is passed to the NotifyStableUnicastIpAddressTable function when it is registering the driver for notifications.

IN PMIB_UNICASTIPADDRESS_TABLE AddressTable

A pointer to a MIB_UNICASTIPADDRESS_TABLE structure that contains the stable unicast IP address table on the local computer.

 

The NotifyStableUnicastIpAddressTable function is used primarily by drivers that use the Teredo client.

To cancel the notification after the callback is complete, call the CancelMibChangeNotify2 function, passing the NotificationHandle parameter that NotifyStableUnicastIpAddressTable returns.

Requirements

Target platform

Universal

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Netioapi.h (include Netioapi.h)

Library

OneCoreUAP.lib on Windows 10

IRQL

< DISPATCH_LEVEL

See also

CancelMibChangeNotify2
CreateUnicastIpAddressEntry
DeleteUnicastIpAddressEntry
GetTeredoPort
GetUnicastIpAddressEntry
GetUnicastIpAddressTable
InitializeUnicastIpAddressEntry
MIB_NOTIFICATION_TYPE
MIB_UNICASTIPADDRESS_ROW
MIB_UNICASTIPADDRESS_TABLE
NotifyTeredoPortChange
NotifyUnicastIpAddressChange
SetUnicastIpAddressEntry

 

 

Send comments about this topic to Microsoft

Show: