NotifyUnicastIpAddressChange 関数 (netioapi.h)

NotifyUnicastIpAddressChange 関数は、ローカル コンピューター上のすべてのユニキャスト IP インターフェイス、ユニキャスト IPv4 アドレス、またはユニキャスト IPv6 アドレスに対する変更について通知されるように登録します。

構文

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyUnicastIpAddressChange(
  [in]      ADDRESS_FAMILY                     Family,
  [in]      PUNICAST_IPADDRESS_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

変更が発生したときに呼び出す関数へのポインター。 この関数は、ユニキャスト IP アドレス通知を受信したときに呼び出されます。

[in] CallerContext

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

[in] InitialNotification

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

[in, out] NotificationHandle

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

戻り値

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

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

注釈

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

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

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

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

変更が発生し、Row パラメーターが NULL でない場合にコールバック関数を受信すると、Row パラメーターで渡されるMIB_UNICASTIPADDRESS_ROW構造体へのポインターに不完全なデータが含まれます。 MIB_UNICASTIPADDRESS_ROW構造体で返される情報は、アプリケーションが GetUnicastIpAddressEntry 関数を呼び出して、変更された IP アドレスに関する完全な情報を照会するのに十分な情報のみです。 コールバック関数を受信すると、アプリケーションはMIB_UNICASTIPADDRESS_ROW構造体を割り当て、受け取った Row パラメーターが指すMIB_UNICASTIPADDRESS_ROW構造体の Address、InterfaceLuid、InterfaceIndex の各メンバーで初期化する必要があります。 この新しく初期化された MIB_UNICASTIPADDRESS_ROW 構造体へのポインターを GetUnicastIpAddressEntry 関数に渡して、変更されたユニキャスト IP アドレスに関する完全な情報を取得する必要があります。

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

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

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

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

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

要件

こちらもご覧ください

CancelMibChangeNotify2

CreateUnicastIpAddressEntry

DeleteUnicastIpAddressEntry

GetUnicastIpAddressEntry

GetUnicastIpAddressTable

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

InitializeUnicastIpAddressEntry

MIB_NOTIFICATION_TYPE

MIB_UNICASTIPADDRESS_ROW

MIB_UNICASTIPADDRESS_TABLE

NotifyStableUnicastIpAddressTable

SetUnicastIpAddressEntry