NotifyIpInterfaceChange 関数 (netioapi.h)

[アーティクル]
03/15/2023

NotifyIpInterfaceChange 関数は、ローカルコンピューター上のすべての IP インターフェイス、IPv4 インターフェイス、または IPv6 インターフェイスに対する変更を通知するように登録します。

構文

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyIpInterfaceChange(
  [in]      ADDRESS_FAMILY               Family,
  [in]      PIPINTERFACE_CHANGE_CALLBACK Callback,
  [in]      PVOID                        CallerContext,
  [in]      BOOLEAN                      InitialNotification,
  [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 の両方の変更通知に登録されます。
AF_INET 2	インターネットプロトコルバージョン 4 (IPv4) アドレスファミリ。このパラメーターを指定すると、この関数は IPv4 変更通知のみに登録されます。
AF_INET6 23	インターネットプロトコルバージョン 6 (IPv6) アドレスファミリ。このパラメーターを指定すると、この関数は IPv6 変更通知にのみ登録されます。

[in] Callback

変更が発生したときに呼び出す関数へのポインター。この関数は、インターフェイス通知を受信したときに呼び出されます。

[in] CallerContext

インターフェイス通知を受信したときに Callback パラメーターで指定された コールバック 関数に渡されるユーザーコンテキスト。

[in] InitialNotification

変更通知の登録が完了した直後にコールバックを呼び出す必要があるかどうかを示す値。この初期通知は、IP インターフェイスに対して変更が発生したことを示すものではありません。コールバックが登録されていることを確認するためのこのパラメーターの目的。

[in, out] NotificationHandle

後で変更通知の登録解除に使用できるハンドルを返すために使用されるポインター。成功すると、このパラメーターに通知ハンドルが返されます。エラーが発生した場合は、 NULL が返されます。

戻り値

関数が成功した場合、戻り値はNO_ERROR。

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

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

注釈

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

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

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

パラメーター	説明
IN PVOID CallerContext	通知の登録時に NotifyIpInterfaceChange 関数に渡される CallerContext パラメーター。
IN PMIB_IPINTERFACE_ROW Row OPTIONAL	変更されたインターフェイスの MIB_IPINTERFACE_ROW エントリへのポインター。 NotificationType パラメーターでコールバック関数に渡されるMIB_NOTIFICATION_TYPE値が MibInitialNotification に設定されている場合、このパラメーターは NULL ポインターです。これは、通知の登録時に NotifyIpInterfaceChange に渡された InitialNotification パラメーターが TRUE に設定されている場合にのみ発生します。
IN MIB_NOTIFICATION_TYPE NotificationType	通知の種類。このメンバーには、Netioapi.h ヘッダーファイルで定義されているMIB_NOTIFICATION_TYPE列挙型の値のいずれかを指定できます。

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

変更が発生し、Row パラメーターが NULL でないときにコールバック関数を受信すると、Row パラメーターで渡されるMIB_IPINTERFACE_ROW構造体へのポインターに不完全なデータが含まれます。 MIB_IPINTERFACE_ROW構造体で返される情報は、アプリケーションが GetIpInterfaceEntry 関数を呼び出して、変更された IP インターフェイスに関する完全な情報を照会するのに十分な情報にすぎません。コールバック関数を受信すると、アプリケーションはMIB_IPINTERFACE_ROW構造体を割り当て、受け取った Row パラメーターが指すMIB_IPINTERFACE_ROW構造体の Family、InterfaceLuid、InterfaceIndex メンバーを使用して初期化する必要があります。この新しく初期化された MIB_IPINTERFACE_ROW 構造体へのポインターを GetIpInterfaceEntry 関数に渡して、変更された IP インターフェイスに関する完全な情報を取得する必要があります。

コールバック表示で使用される Row パラメーターによって指されるメモリは、オペレーティングシステムによって管理されます。通知を受け取るアプリケーションは 、Row パラメーターが指すメモリを解放しようとしないでください。

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

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

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

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

要件

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