NotifyRouteChange2 関数 (netioapi.h)
NotifyRouteChange2 関数は、ローカル コンピューター上の IP ルート エントリに対する変更を通知するように登録します。
構文
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyRouteChange2(
[in] ADDRESS_FAMILY AddressFamily,
[in] PIPFORWARD_CHANGE_CALLBACK Callback,
[in] PVOID CallerContext,
[in] BOOLEAN InitialNotification,
[in, out] HANDLE *NotificationHandle
);
パラメーター
[in] AddressFamily
変更通知に登録するアドレス ファミリ。
アドレス ファミリに使用できる値は、 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です。
| 値 | 説明 |
|---|---|
|
IPv4 ルート変更通知のみに登録します。 |
|
IPv6 ルート変更通知のみに登録します。 |
|
IPv4 と IPv6 の両方のルート変更通知に登録します。 |
[in] Callback
変更が発生したときに呼び出す関数へのポインター。 この関数は、IP ルート通知を受信したときに呼び出されます。
[in] CallerContext
IP ルート通知を受信したときに Callback パラメーターで指定された コールバック 関数に渡されるユーザー コンテキスト。
[in] InitialNotification
変更通知の登録が完了した直後にコールバックを呼び出す必要があるかどうかを示す 値。 この初期通知は、IP ルート エントリに対して変更が発生したことを示すものではありません。 コールバックが登録されていることを確認するためのこのパラメーターの目的。
[in, out] NotificationHandle
変更通知の登録解除に後で使用できるハンドルを返すために使用されるポインター。 成功すると、このパラメーターで通知ハンドルが返されます。 エラーが発生した場合は、 NULL が返されます。
戻り値
関数が成功した場合、戻り値はNO_ERROR。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
| リターン コード | 説明 |
|---|---|
|
無効なハンドルが検出された場合に内部エラーが発生しました。 |
|
無効なパラメーターが関数に渡されました。 Family パラメーターがAF_INET、AF_INET6、またはAF_UNSPECのいずれでもなかった場合、このエラーが返されます。 |
|
メモリが不足していました。 |
|
FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。 |
解説
NotifyRouteChange2 関数は、Windows Vista 以降で定義されています。
Family パラメーターは、AF_INET、AF_INET6、またはAF_UNSPECのいずれかに設定する必要があります。
Callback パラメーターで指定されたコールバック関数の呼び出しがシリアル化されます。 コールバック関数は VOID 型の関数として定義する必要があります。 コールバック関数に渡されるパラメーターには、次のものがあります。
| パラメーター | 説明 |
|---|---|
| IN PVOID CallerContext | 通知の登録時に NotifyRouteChange2 関数に渡される CallerContext パラメーター。 |
| IN PMIB_IPFORWARD_ROW2 Row OPTIONAL | 変更された IP ルート エントリの MIB_IPFORWARD_ROW2 エントリへのポインター。 NotificationType パラメーターでコールバック関数に渡されるMIB_NOTIFICATION_TYPE値が MibInitialNotification に設定されている場合、このパラメーターは NULL ポインターです。 これは、通知に登録するときに NotifyRouteChange2 に渡された InitialNotification パラメーターが TRUE に設定されている場合にのみ発生します。 |
| IN MIB_NOTIFICATION_TYPE NotificationType | 通知の種類。 このメンバーは、Netioapi.h ヘッダー ファイルで定義されているMIB_NOTIFICATION_TYPE列挙型の値のいずれかになります。 |
Callback パラメーターで指定されたコールバック関数は、NotifyRouteChange2 関数を呼び出すアプリケーションと同じプロセスで実装する必要があります。 コールバック関数が別の DLL 内にある場合は、 NotifyRouteChange2 関数を呼び出して変更通知を登録する前に DLL を読み込む必要があります。
変更が発生し、Row パラメーターが NULL でない場合にコールバック関数を受信すると、Row パラメーターで渡されるMIB_IPFORWARD_ROW2構造体へのポインターに不完全なデータが含まれます。 MIB_IPFORWARD_ROW2構造体で返される情報は、アプリケーションが GetIpForwardEntry2 関数を呼び出して、変更された IP ルートに関する完全な情報を照会するのに十分な情報のみです。 コールバック関数を受信すると、アプリケーションはMIB_IPFORWARD_ROW2構造体を割り当て、受信した Row パラメーターによって指されるMIB_IPFORWARD_ROW2構造体の DestinationPrefix、NextHop、InterfaceLuid、InterfaceIndex の各メンバーで初期化する必要があります。 この新しく初期化された MIB_IPFORWARD_ROW2 構造体へのポインターを GetIpForwardEntry2 関数に渡して、変更された IP ルートに関する完全な情報を取得する必要があります。
コールバック表示で使用される Row パラメーターによって指されるメモリは、オペレーティング システムによって管理されます。 通知を受け取るアプリケーションでは、 Row パラメーターが指すメモリを解放しないでください。
NotifyRouteChange2 関数を呼び出して変更通知を登録すると、アプリケーションが変更通知の登録を解除するか、アプリケーションが終了するまで、これらの通知は引き続き送信されます。 アプリケーションが終了すると、システムは変更通知の登録を自動的に登録解除します。 アプリケーションが終了する前に、変更通知の登録を明示的に解除することをお勧めします。
システムがシャットダウンまたは再起動された場合、変更通知の登録は保持されません。
変更通知の登録を解除するには、NotifyRouteChange2 によって返される NotificationHandle パラメーターを渡して CancelMibChangeNotify2 関数を呼び出します。
アプリケーションは、同じ NotificationHandle パラメーターの通知コールバック関数を現在実行しているスレッドのコンテキストから CancelMibChangeNotify2 関数を呼び出すことはできません。 それ以外の場合、そのコールバックを実行しているスレッドはデッドロックになります。 そのため、 CancelMibChangeNotify2 関数を通知コールバック ルーチンの一部として直接呼び出すことはできません。 より一般的な状況では、 CancelMibChangeNotify2 関数を実行するスレッドは、通知コールバック操作を実行するスレッドが待機するリソースを所有できません。これは、同様のデッドロックが発生するためです。 CancelMibChangeNotify2 関数は、通知コールバックを受け取るスレッドに依存関係がない別のスレッドから呼び出す必要があります。
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | netioapi.h (Iphlpapi.h を含む) |
| Library | Iphlpapi.lib |
| [DLL] | Iphlpapi.dll |