NotifyUnicastIpAddressChange-Funktion

Artikel
06/15/2023

Die NotifyUnicastIpAddressChange-Funktion registriert den Treiber, um über Änderungen an allen Unicast-IP-Schnittstellen, Unicast-IPv4-Adressen oder Unicast-IPv6-Adressen auf einem lokalen Computer benachrichtigt zu werden.

Syntax

NETIOAPI_API NotifyUnicastIpAddressChange(
  _In_    ADDRESS_FAMILY                     Family,
  _In_    PUNICAST_IPADDRESS_CHANGE_CALLBACK Callback,
  _In_    PVOID                              CallerContext,
  _In_    BOOLEAN                            InitialNotification,
  _Inout_ HANDLE                             *NotificationHandle
);

Parameter

Familie [in]
Die Adressfamilie, für die der Treiber für Änderungsbenachrichtigungen registriert werden soll.

Mögliche Werte für die Adressfamilie sind in der Winsock2.h-Headerdatei 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 Sie beide Konstanten verwenden können.

Unter Windows Vista und höheren Versionen der Windows-Betriebssysteme sind mögliche Werte für den Family-Parameter in der Ws2def.h-Headerdatei definiert. Beachten Sie, dass die Ws2def.h-Headerdatei automatisch in Netioapi.h enthalten ist und Sie Ws2def.h niemals direkt verwenden sollten.

Die folgenden Werte werden derzeit für die Adressfamilie unterstützt:
- AF_INET
  Die IPv4-Adressfamilie. Wenn dieser Wert angegeben wird, registriert die Funktion den Treiber nur für Unicast-IPv4-Adressänderungsbenachrichtigungen.
- AF_INET6
  Die IPv6-Adressfamilie. Wenn dieser Wert angegeben wird, registriert die Funktion den Treiber nur für Unicast-IPv6-Adressänderungsbenachrichtigungen.
- AF_UNSPEC
  Die Adressfamilie ist nicht angegeben. Wenn dieser Wert angegeben ist, registriert die Funktion den Treiber sowohl für Unicast-IPv4- als auch für IPv6-Adressänderungsbenachrichtigungen.
Rückruf [in]
Ein Zeiger auf die Funktion, die bei einer Änderung aufgerufen werden soll. Diese Funktion wird aufgerufen, wenn eine Unicast-IP-Adressbenachrichtigung empfangen wird.
CallerContext [in]
Ein Benutzerkontext, der an die Rückruffunktion übergeben wird, die im Rückrufparameter angegeben wird, wenn eine Schnittstellenbenachrichtigung empfangen wird.
InitialNotification [in]
Ein -Wert, der angibt, ob der Rückruf unmittelbar nach Abschluss der Registrierung für die Änderungsbenachrichtigung aufgerufen werden soll. Diese anfängliche Benachrichtigung gibt nicht an, dass eine Änderung an einer Unicast-IP-Adresse aufgetreten ist. Dieser Parameter stellt eine Bestätigung bereit, dass der Rückruf registriert wurde.
NotificationHandle [in, out]
Ein Zeiger, der verwendet wird, um ein Handle zurückzugeben, das Ihr Treiber später verwenden kann, um die Registrierung der Treiberänderungsbenachrichtigung aufzuheben. Bei Erfolg wird in diesem Parameter ein Benachrichtigungshandle zurückgegeben. Wenn ein Fehler auftritt, wird NULL zurückgegeben.

Rückgabewert

NotifyUnicastIpAddressChange gibt STATUS_SUCCESS zurück, wenn die Funktion erfolgreich ist.

Wenn die Funktion fehlschlägt, gibt NotifyUnicastIpAddressChange einen der folgenden Fehlercodes zurück:

Rückgabecode	Beschreibung
ERROR_INVALID_HANDLE	Es ist ein interner Fehler aufgetreten, bei dem ein ungültiges Handle aufgetreten ist.
STATUS_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 war.
STATUS_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden.
Andere	Verwenden Sie die FormatMessage-Funktion , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Bemerkungen

Ihr Treiber muss den Family-Parameter entweder auf AF_INET, AF_INET6 oder AF_UNSPEC festlegen.

Der Aufruf der Rückruffunktion, die im Callback-Parameter angegeben ist, wird serialisiert. Die Rückruffunktion sollte als Funktion vom Typ VOID definiert werden. Die Parameter, die an die Rückruffunktion übergeben werden, umfassen Folgendes.

Parameter	BESCHREIBUNG
IN PVOID CallerContext	Der CallerContext-Parameter , der an die NotifyUnicastIpAddressChange-Funktion übergeben wird, wenn der Treiber für Änderungsbenachrichtigungen registriert wird.
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. Diese Situation kann nur auftreten, wenn der InitialNotification-Parameter , der an NotifyUnicastIpAddressChange übergeben wird, beim Registrieren des Treibers für Änderungsbenachrichtigungen auf TRUE festgelegt wurde.
IN MIB_NOTIFICATION_TYPE NotificationType	Der Benachrichtigungstyp. Dieser Member kann einer der Werte aus dem MIB_NOTIFICATION_TYPE Enumerationstyp sein.

Um die Registrierung des Treibers für Änderungsbenachrichtigungen aufzuheben, rufen Sie die CancelMibChangeNotify2-Funktion auf, und übergeben Sie den NotificationHandle-Parameter , den NotifyUnicastIpAddressChange zurückgibt.

Anforderungen

Zielplattform	Universell
Version	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Header	Netioapi.h (netioapi.h einschließen)
Bibliothek	Netio.lib
IRQL	< DISPATCH_LEVEL