NotifyIpInterfaceChange 関数 (netioapi.h)
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です。
[in] Callback
変更が発生したときに呼び出す関数へのポインター。 この関数は、インターフェイス通知を受信したときに呼び出されます。
[in] CallerContext
インターフェイス通知を受信したときに Callback パラメーターで指定された コールバック 関数に渡されるユーザー コンテキスト。
[in] InitialNotification
変更通知の登録が完了した直後にコールバックを呼び出す必要があるかどうかを示す 値。 この初期通知は、IP インターフェイスに対して変更が発生したことを示すものではありません。 コールバックが登録されていることを確認するためのこのパラメーターの目的。
[in, out] NotificationHandle
後で変更通知の登録解除に使用できるハンドルを返すために使用されるポインター。 成功すると、このパラメーターに通知ハンドルが返されます。 エラーが発生した場合は、 NULL が返されます。
戻り値
関数が成功した場合、戻り値はNO_ERROR。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
| リターン コード | 説明 |
|---|---|
|
無効なハンドルが検出された場所で内部エラーが発生しました。 |
|
無効なパラメーターが関数に渡されました。 Family パラメーターがAF_INET、AF_INET6、またはAF_UNSPECでなかった場合、このエラーが返されます。 |
|
メモリが不足していました。 |
|
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 |