NotifyRouteChange 関数 (iphlpapi.h)

  • [アーティクル]

NotifyRouteChange 関数を使用すると、IPv4 ルーティング テーブルで変更が発生するたびに、呼び出し元に通知が送信されます。

構文

IPHLPAPI_DLL_LINKAGE DWORD NotifyRouteChange(
  [out] PHANDLE      Handle,
  [in]  LPOVERLAPPED overlapped
);

パラメーター

[out] Handle

非同期通知で使用するハンドルを受け取る HANDLE 変数へのポインター。

[in] overlapped

ルーティング テーブルの変更を呼び出し元に通知する OVERLAPPED 構造体へのポインター。

戻り値

関数が成功した場合、呼び出し元が Handle パラメーターと重複するパラメーターに NULL を指定した場合、戻り値はNO_ERRORされます。 呼び出し元が NULL 以外のパラメーターを指定した場合、成功の戻り値はERROR_IO_PENDING。 関数が失敗した場合は、 FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。

リターン コード 説明
ERROR_CANCELLED
 コンテキストは登録解除されているため、呼び出しはすぐに取り消されました。
ERROR_INVALID_PARAMETER
 無効なパラメーターが渡されました。 このエラーは、 Handle パラメーターと 重複する パラメーターの両方が NULL ではないが、入力パラメーターで指定されたメモリを呼び出し元のプロセスで書き込むことができない場合に返されます。 このエラーは、クライアントが変更通知要求を既に行っている場合にも返されるため、この重複する要求は失敗します。
ERROR_NOT_ENOUGH_MEMORY
 操作を完了するために使用できるメモリが不足していました。
ERROR_NOT_SUPPORTED
 このエラーは、Windows 98/95 や Windows NT 4.0 など、この関数がサポートされていない Windows のバージョンで返されます。

解説

次に、
NotifyRouteChange 関数は、次の 2 つの方法で呼び出される場合があります。

  • 同期メソッド
  • 非同期メソッド

呼び出し元が Handle パラメーターと重複するパラメーターに NULL を指定した場合、NotifyRouteChange の呼び出しは同期的であり、IPv4 ルーティング テーブルの変更が発生するまでブロックされます。 この場合、変更が発生した場合、 NotifyRouteChange 関数は変更が発生したことを示すために完了します。

NotifyRouteChange 関数が同期的に呼び出されると、アプリケーションが終了するまで、次の IPv4 ルーティング変更時に通知が送信されます。

呼び出し元がハンドル変数と OVERLAPPED 構造体を指定した場合、呼び出し元は、返されたハンドルと OVERLAPPED 構造体を使用して、IPv4 ルーティング テーブルの変更に関する非同期通知を受信できます。 ハンドルと OVERLAPPED 構造体を使用して通知を受信する方法については、次のトピックを参照してください。

アプリケーションが通知を受信し、次の変更の通知が必要な場合は、 NotifyRouteChange 関数を再度呼び出す必要があります。

CancelIPChangeNotify 関数は、IP アドレスの通知を取り消し、NotifyAddrChange 関数または NotifyRouteChange 関数を正常に呼び出して以前に要求した変更をルーティングします。

アプリケーションに変更が通知されると、アプリケーションは GetIpForwardTable または GetIpForwardTable2 関数を呼び出して IPv4 ルーティング テーブルを取得し、変更された内容を確認できます。 アプリケーションに通知され、次の変更の通知が必要な場合は、 NotifyRouteChange 関数を再度呼び出す必要があります。

NotifyRouteChange 関数が非同期的に呼び出された場合、アプリケーションが CancelIPChangeNotify 関数を呼び出して通知を取り消すか、アプリケーションが終了するまで、次の IPv4 ルート変更で通知が送信されます。 アプリケーションが終了すると、システムは通知の登録を自動的に取り消します。 アプリケーションが終了する前に、通知を明示的にキャンセルすることをお勧めします。

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

Windows Vista 以降では、 NotifyRouteChange2 関数を使用して登録し、ローカル コンピューター上の IPv6 ルーティング テーブルに対する変更を通知できます。

例

次の例では、IP ルーティング テーブルで変更が発生するのを待機します。

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <windows.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

void main()
{
  OVERLAPPED overlap;
  DWORD ret;
    
  HANDLE hand = NULL;
  overlap.hEvent = WSACreateEvent();

  ret = NotifyRouteChange(&hand, &overlap);

  if (ret != NO_ERROR)
  {
    if (WSAGetLastError() != WSA_IO_PENDING)
    {
      printf("NotifyRouteChange error...%d\n", WSAGetLastError());            
      return;
    }
  }

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("Routing table changed..\n");
}

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー iphlpapi.h
Library Iphlpapi.lib
[DLL] Iphlpapi.dll

関連項目

CancelIPChangeNotify

GetIpForwardTable

GetIpForwardTable2

GetOverlappedResult

IP ヘルパー関数リファレンス

NotifyAddrChange

OVERLAPPED