NotifyUnicastIpAddressChange-Funktion (netioapi.h)

Artikel
08/25/2023

Die NotifyUnicastIpAddressChange-Funktion registriert sich für Änderungen an allen Unicast-IP-Schnittstellen, Unicast-IPv4-Adressen oder Unicast-IPv6-Adressen auf einem lokalen Computer.

Syntax

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
);

Parameter

[in] Family

Die Adressfamilie, für die Änderungsbenachrichtigungen registriert werden sollen.

Mögliche Werte für die Adressfamilie sind in der Headerdatei Winsock2.h aufgeführt. Beachten Sie, dass die Werte für die AF_ Adressfamilie und PF_ Protokollfamilienkonstanten identisch sind (z. B. AF_INET und PF_INET), sodass beide Konstanten verwendet werden können.

Auf der Windows SDK für Windows Vista und höher veröffentlicht, wurden die organization der Headerdateien geändert, und mögliche Werte für diesen Member sind in der Headerdatei Ws2def.h definiert. Beachten Sie, dass die Ws2def.h-Headerdatei automatisch in Winsock2.h enthalten ist und nie direkt verwendet werden sollte.

Die derzeit unterstützten Werte sind AF_INET, AF_INET6 und AF_UNSPEC.

Wert	Bedeutung
AF_INET	Registrieren Sie sich nur für Unicast-IPv4-Adressänderungsbenachrichtigungen.
AF_INET6	Registrieren Sie sich nur für Unicast-IPv6-Adressänderungsbenachrichtigungen.
AF_UNSPEC	Registrieren Sie sich sowohl für Unicast-IPv4- als auch für IPv6-Adressänderungsbenachrichtigungen.

[in] Callback

Ein Zeiger auf die Funktion, die bei einer Änderung aufgerufen werden soll. Diese Funktion wird aufgerufen, wenn eine Unicast-IP-Adressbenachrichtigung empfangen wird.

[in] CallerContext

Ein Benutzerkontext, der an die Rückruffunktion übergeben wird, die im Rückrufparameter angegeben ist, wenn eine Schnittstellenbenachrichtigung empfangen wird.

[in] InitialNotification

Ein Wert, der angibt, ob der Rückruf unmittelbar nach Abschluss der Registrierung für änderungsbenachrichtigungen aufgerufen werden soll. Diese anfängliche Benachrichtigung weist nicht darauf hin, dass eine Änderung an einer Unicast-IP-Adresse aufgetreten ist. Der Zweck dieses Parameters, um die Bestätigung zu geben, dass der Rückruf registriert ist.

[in, out] NotificationHandle

Ein Zeiger, der verwendet wird, um ein Handle zurückzugeben, das später zum Aufheben der Registrierung der Änderungsbenachrichtigung verwendet werden kann. Bei erfolgreicher Ausführung wird in diesem Parameter ein Benachrichtigungshandle zurückgegeben. Wenn ein Fehler auftritt, wird NULL zurückgegeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.

Rückgabecode	Beschreibung
ERROR_INVALID_HANDLE	Es ist ein interner Fehler aufgetreten, bei dem ein ungültiges Handle aufgetreten ist.
ERROR_INVALID_PARAMETER	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn der Family-Parameter weder AF_INET, AF_INET6 noch AF_UNSPEC wurde.
ERROR_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden.
Andere	Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die NotifyUnicastIpAddressChange-Funktion ist unter Windows Vista und höher definiert.

Der Family-Parameter muss entweder auf AF_INET, AF_INET6 oder AF_UNSPEC festgelegt werden.

Der Aufruf der Rückruffunktion, die im Rückrufparameter angegeben ist, wird serialisiert. Die Rückruffunktion sollte als Funktion des Typs VOID definiert werden. Zu den Parametern, die an die Rückruffunktion übergeben werden, gehören Folgendes:

Parameter	BESCHREIBUNG
IN PVOID CallerContext	Der CallerContext-Parameter , der bei der Registrierung für Benachrichtigungen an die Funktion NotifyUnicastIpAddressChange übergeben wurde.
IN PMIB_UNICASTIPADDRESS_ROW Zeile OPTIONAL	Ein Zeiger auf den MIB_UNICASTIPADDRESS_ROW Eintrag für die geänderte Unicast-IP-Adresse. Dieser Parameter ist ein NULL-Zeiger , wenn der MIB_NOTIFICATION_TYPE Wert, der im NotificationType-Parameter an die Rückruffunktion übergeben wird, auf MibInitialNotification festgelegt ist. Dies kann nur auftreten, wenn der an NotifyUnicastIpAddressChange übergebeneInitialNotification-Parameter bei der Registrierung für Benachrichtigungen auf TRUE festgelegt wurde.
IN MIB_NOTIFICATION_TYPE NotificationType	Der Benachrichtigungstyp. Dieses Element kann einer der Werte aus dem MIB_NOTIFICATION_TYPE Enumerationstyp sein, der in der Headerdatei Netioapi.h definiert ist.

Die im Rückrufparameter angegebene Rückruffunktion muss im gleichen Prozess implementiert werden wie die Anwendung, die die Funktion NotifyUnicastIpAddressChange aufruft . Wenn sich die Rückruffunktion in einer separaten DLL befindet, sollte die DLL geladen werden, bevor die NotifyUnicastIpAddressChange-Funktion aufgerufen wird, um sich für Änderungsbenachrichtigungen zu registrieren.

Wenn die Rückruffunktion empfangen wird, wenn eine Änderung erfolgt und der Row-Parameter nicht NULL ist, enthält der Zeiger auf die im Row-Parameter übergebene MIB_UNICASTIPADDRESS_ROW Struktur unvollständige Daten. Die in der MIB_UNICASTIPADDRESS_ROW-Struktur zurückgegebenen Informationen sind nur genügend Informationen, die eine Anwendung die GetUnicastIpAddressEntry-Funktion aufrufen kann, um vollständige Informationen zur IP-Adresse abzufragen, die sich geändert hat. Wenn die Rückruffunktion empfangen wird, sollte eine Anwendung eine MIB_UNICASTIPADDRESS_ROW Struktur zuordnen und sie mit den Membern Address, InterfaceLuid und InterfaceIndex in der MIB_UNICASTIPADDRESS_ROW Struktur initialisieren, auf die der empfangene Row-Parameter verweist. Ein Zeiger auf diese neu initialisierte MIB_UNICASTIPADDRESS_ROW-Struktur sollte an die GetUnicastIpAddressEntry-Funktion übergeben werden, um vollständige Informationen zur unicast-IP-Adresse abzurufen, die geändert wurde.

Der Speicher, auf den der Row-Parameter verweist, der in den Rückrufanzeigen verwendet wird, wird vom Betriebssystem verwaltet. Eine Anwendung, die eine Benachrichtigung empfängt, sollte niemals versuchen, den Speicher freizugeben, auf den der Row-Parameter verweist.

Sobald die NotifyUnicastIpAddressChange-Funktion aufgerufen wurde, um sich für Änderungsbenachrichtigungen zu registrieren, werden diese Benachrichtigungen weiterhin gesendet, bis die Anwendung die Registrierung für Änderungsbenachrichtigungen auflöst oder die Anwendung beendet wird. Wenn die Anwendung beendet wird, hebt das System die Registrierung für Änderungsbenachrichtigungen automatisch auf. Es wird weiterhin empfohlen, dass eine Anwendung die Registrierung für Änderungsbenachrichtigungen explizit aufhebt, bevor sie beendet wird.

Die Registrierung für Änderungsbenachrichtigungen wird nicht beibehalten, wenn das System heruntergefahren oder neu gestartet wird.

Um die Registrierung für Änderungsbenachrichtigungen aufzuheben, rufen Sie die CancelMibChangeNotify2-Funktion auf und übergeben den von NotifyUnicastIpAddressChange zurückgegebenenNotificationHandle-Parameter.

Eine Anwendung kann keine Funktion CancelMibChangeNotify2 aus dem Kontext des Threads aufrufen, der derzeit die Benachrichtigungsrückruffunktion für denselben NotificationHandle-Parameter ausführt. Andernfalls führt der Thread, der diesen Rückruf ausführt, zu einem Deadlock. Daher darf die CancelMibChangeNotify2-Funktion nicht direkt als Teil der Benachrichtigungsrückrufroutine aufgerufen werden. In einer allgemeineren Situation kann ein Thread, der die CancelMibChangeNotify2-Funktion ausführt, keine Ressource besitzen, für die der Thread, der einen Benachrichtigungsrückrufvorgang ausführt, warten würde, da dies zu einem ähnlichen Deadlock führen würde. Die CancelMibChangeNotify2-Funktion sollte von einem anderen Thread aufgerufen werden, von dem der Thread, der den Benachrichtigungsrückruf empfängt, keine Abhängigkeiten aufweist.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	netioapi.h (include Iphlpapi.h)
Bibliothek	Iphlpapi.lib
DLL	Iphlpapi.dll