NotifyStableUnicastIpAddressTable 関数 (netioapi.h)

[アーティクル]
08/25/2023

NotifyStableUnicastIpAddressTable 関数は、ローカルコンピューター上の安定したユニキャスト IP アドレステーブルを取得します。

構文

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
  [in]      ADDRESS_FAMILY                           Family,
  [in, out] PMIB_UNICASTIPADDRESS_TABLE              *Table,
  [in]      PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  [in]      PVOID                                    CallerContext,
  [in, out] HANDLE                                   *NotificationHandle
);

パラメーター

[in] Family

取得するアドレスファミリ。

アドレスファミリに使用できる値は、 Winsock2.h ヘッダーファイルに一覧表示されます。 AF_ アドレスファミリ定数とPF_ プロトコルファミリ定数の値は同一であるため ( たとえば、AF_INET と PF_INET)、どちらの定数も使用できます。

Windows Vista 以降用にリリースされたWindows SDKでは、ヘッダーファイルのorganizationが変更され、このメンバーの使用可能な値は Ws2def.h ヘッダーファイルで定義されます。 Ws2def.h ヘッダーファイルは Winsock2.h に自動的に含まれるので、直接使用しないでください。

現在サポートされている値は 、AF_INET、 AF_INET6、 AF_UNSPECです。

値	意味
AF_UNSPEC 0	アドレスファミリが指定されていません。このパラメーターを指定すると、この関数は IPv4 エントリと IPv6 エントリの両方を含む安定したユニキャスト IP アドレステーブルを取得します。
AF_INET 2	インターネットプロトコルバージョン 4 (IPv4) アドレスファミリ。このパラメーターを指定すると、関数は IPv4 エントリのみを含む安定したユニキャスト IP アドレステーブルを取得します。
AF_INET6 23	インターネットプロトコルバージョン 6 (IPv6) アドレスファミリ。このパラメーターを指定すると、関数は IPv6 エントリのみを含む安定したユニキャスト IP アドレステーブルを取得します。

[in, out] Table

MIB_UNICASTIPADDRESS_TABLE構造体へのポインター。 NotifyStableUnicastIpAddressTable が成功すると、このパラメーターはローカルコンピューター上の安定したユニキャスト IP アドレステーブルを返します。

NotifyStableUnicastIpAddressTable が I/O 要求が保留中であることを示すERROR_IO_PENDINGを返すと、安定したユニキャスト IP アドレステーブルが CallerCallback パラメーターの関数に返されます。

[in] CallerCallback

安定したユニキャスト IP アドレステーブルを使用して呼び出す関数へのポインター。この関数は、 NotifyStableUnicastIpAddressTable が ERROR_IO_PENDINGを返し、I/O 要求が保留中であることを示す場合に呼び出されます。

[in] CallerContext

安定したユニキャスト IP アドレステーブル si が使用可能な場合に 、CallerCallback パラメーターで指定されたコールバック関数に渡されるユーザーコンテキスト。

[in, out] NotificationHandle

安定したユニキャスト IP アドレステーブルを取得する要求を取り消すために使用できるハンドルを返すために使用されるポインター。このパラメーターは、I/O 要求が保留中であることを示す NotifyStableUnicastIpAddressTable からの戻り値が ERROR_IO_PENDING 場合に返されます。

戻り値

関数がすぐに成功した場合、戻り値はNO_ERRORされ、安定したユニキャスト IP テーブルが Table パラメーターで返されます。

I/O 要求が保留中の場合、関数は ERROR_IO_PENDING を返し、I/O 要求が安定したユニキャスト IP アドレステーブルで完了したときに CallerCallback パラメーターが指す関数が呼び出されます。

関数が失敗した場合、戻り値は次のいずれかのエラーコードになります。

リターンコード	説明
ERROR_INVALID_HANDLE	無効なハンドルが検出された場合に内部エラーが発生しました。
ERROR_INVALID_PARAMETER	無効なパラメーターが関数に渡されました。このエラーは、 Table パラメーターが NULL ポインターだった場合、 NotificationHandle パラメーターが NULL ポインターだった場合、または Family パラメーターが AF_INET、 AF_INET6、またはAF_UNSPECのいずれにもなかった場合に返されます。
ERROR_NOT_ENOUGH_MEMORY	メモリが不足していました。
その他	FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。

注釈

NotifyStableUnicastIpAddressTable 関数は、Windows Vista 以降で定義されています。

NotifyStableUnicastIpAddressTable 関数が直ちに成功した場合、戻り値はNO_ERRORされ、Table パラメーターで安定したユニキャスト IP テーブルが返されます。呼び出し元のアプリケーションは、MIB_UNICASTIPADDRESS_TABLE情報が不要になった場合に、FreeMibTable 関数を使用して Table パラメーターが指すメモリを解放する必要があります。

ダイヤルオンデマンドアドレスを除くすべてのユニキャスト IP アドレスは、優先状態の場合にのみ安定していると見なされます。通常のユニキャスト IP アドレスエントリの場合、これは IpDadStatePreferred に設定された IP アドレスのMIB_UNICASTIPADDRESS_ROWの DadState メンバーに対応します。すべてのダイヤルオンデマンドアドレスは、独自の安定性メトリックを定義します。現在、この機能によって考慮されるダイヤルオンデマンドアドレスは、ローカルコンピューター上のTeredo クライアントによって使用されるユニキャスト IP アドレスのみです。

Family パラメーターは、AF_INET、AF_INET6、またはAF_UNSPECのいずれかに設定する必要があります。

NotifyStableUnicastIpAddressTable が成功し、NO_ERRORを返すと、Table パラメーターはローカルコンピューター上の安定したユニキャスト IP アドレステーブルを返します。

NotifyStableUnicastIpAddressTable 関数は、主に Teredo クライアントを使用するアプリケーションによって使用されます。

Teredoによって使用されるユニキャスト IP アドレスがローカルコンピューターで使用できるが、安定した (修飾された) 状態ではない場合、NotifyStableUnicastIpAddressTable はERROR_IO_PENDINGを返し、安定したユニキャスト IP アドレステーブルは最終的に CallerCallback パラメーターで関数を呼び出すことによって返されます。 Teredo アドレスが使用できないか、安定した状態で、他のユニキャスト IP アドレスが安定した状態である場合、CallerCallback パラメーターの関数は呼び出されません。

CallerCallback パラメーターで指定されたコールバック関数は、VOID 型の関数として定義する必要があります。コールバック関数に渡されるパラメーターには、次のものがあります。

パラメーター	説明
IN PVOID CallerContext	通知の登録時に NotifyStableUnicastIpAddressTable 関数に渡される CallerContext パラメーター。
IN PMIB_UNICASTIPADDRESS_TABLE AddressTable	ローカルコンピューター上の安定したユニキャスト IP アドレステーブルを含む MIB_UNICASTIPADDRESS_TABLE へのポインター。

CallerCallback パラメーターで指定されたコールバック関数は、NotifyStableUnicastIpAddressTable 関数を呼び出すアプリケーションと同じプロセスで実装する必要があります。コールバック関数が別の DLL 内にある場合は、 NotifyStableUnicastIpAddressTable 関数を呼び出して変更通知を登録する前に DLL を読み込む必要があります。

コールバック表示で使用される AddressTable パラメーターによって指されるメモリは、オペレーティングシステムによって割り当てられます。通知を受け取るアプリケーションでは、MIB_UNICASTIPADDRESS_TABLE情報が不要になったら、FreeMibTable 関数を使用して AddressTable パラメーターによって指されるメモリを解放する必要があります。

NotifyStableUnicastIpAddressTable 関数を呼び出して変更通知を登録すると、アプリケーションが変更通知の登録を解除するか、アプリケーションが終了するまで、これらの通知は引き続き送信されます。アプリケーションが終了すると、システムは変更通知の登録を自動的に登録解除します。ただし、アプリケーションが終了する前に、変更通知を明示的に登録解除することをお勧めします。

システムがシャットダウンまたは再起動された場合、変更通知の登録は保持されません。

変更通知の登録を解除するには、NotifyStableUnicastIpAddressTable によって返される NotificationHandle パラメーターを渡して CancelMibChangeNotify2 関数を呼び出します。

アプリケーションは、同じ NotificationHandle パラメーターの通知コールバック関数を現在実行しているスレッドのコンテキストから CancelMibChangeNotify2 関数を呼び出すことはできません。それ以外の場合、そのコールバックを実行しているスレッドはデッドロックになります。そのため、 CancelMibChangeNotify2 関数を通知コールバックルーチンの一部として直接呼び出すことはできません。より一般的な状況では、 CancelMibChangeNotify2 関数を実行するスレッドは、通知コールバック操作を実行するスレッドが待機するリソースを所有できません。これは、同様のデッドロックが発生するためです。 CancelMibChangeNotify2 関数は、通知コールバックを受け取るスレッドに依存関係がない別のスレッドから呼び出す必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	netioapi.h (Iphlpapi.h を含む)
Library	Iphlpapi.lib
[DLL]	Iphlpapi.dll