NotifyStableUnicastIpAddressTable-Funktion (netioapi.h)

Artikel
02/29/2024

Die NotifyStableUnicastIpAddressTable-Funktion ruft die stabile Unicast-IP-Adresstabelle auf einem lokalen Computer ab.

Syntax

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
  [in]      ADDRESS_FAMILY                           Family,
  [in, out] PMIB_UNICASTIPADDRESS_TABLE              *Table,
  [in]      PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  [in]      PVOID                                    CallerContext,
  [in, out] HANDLE                                   *NotificationHandle
);

Parameter

[in] Family

Die abzurufende Adressfamilie.

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 beide Konstanten verwendet werden können.

Auf der für Windows Vista und höher veröffentlichten Windows SDK wurde die organization der Headerdateien geändert, und mögliche Werte für dieses Element werden in der Ws2def.h-Headerdatei definiert. Beachten Sie, dass die Ws2def.h-Headerdatei automatisch in Winsock2.h enthalten ist und niemals direkt verwendet werden sollte.

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

Wert	Bedeutung
AF_UNSPEC 0	Die Adressfamilie ist nicht angegeben. Wenn dieser Parameter angegeben ist, ruft die Funktion die stabile Unicast-IP-Adresstabelle ab, die sowohl IPv4- als auch IPv6-Einträge enthält.
AF_INET 2	Die IPv4-Adressfamilie (Internet Protocol Version 4). Wenn dieser Parameter angegeben ist, ruft die Funktion die stabile Unicast-IP-Adresstabelle ab, die nur IPv4-Einträge enthält.
AF_INET6 23	Die IPv6-Adressfamilie (Internet Protocol Version 6). Wenn dieser Parameter angegeben wird, ruft die Funktion die stabile Unicast-IP-Adresstabelle ab, die nur IPv6-Einträge enthält.

[in, out] Table

Ein Zeiger auf eine MIB_UNICASTIPADDRESS_TABLE-Struktur . Wenn NotifyStableUnicastIpAddressTable erfolgreich ist, gibt dieser Parameter die stabile Unicast-IP-Adresstabelle auf dem lokalen Computer zurück.

Wenn NotifyStableUnicastIpAddressTableERROR_IO_PENDING zurückgibt, der angibt, dass die E/A-Anforderung ausstehend ist, wird die stabile Unicast-IP-Adresstabelle an die Funktion im Parameter CallerCallback zurückgegeben.

[in] CallerCallback

Ein Zeiger auf die Funktion, die mit der stabilen Unicast-IP-Adresstabelle aufgerufen werden soll. Diese Funktion wird aufgerufen, wenn NotifyStableUnicastIpAddressTableERROR_IO_PENDING zurückgibt, was angibt, dass die E/A-Anforderung aussteht.

[in] CallerContext

Ein Benutzerkontext, der an die im CallerCallback-Parameter angegebene Rückruffunktion übergeben wird, wenn die stabile Unicast-IP-Adresstabelle verfügbar ist.

[in, out] NotificationHandle

Ein Zeiger, der verwendet wird, um ein Handle zurückzugeben, das zum Abbrechen der Anforderung zum Abrufen der stabilen Unicast-IP-Adresstabelle verwendet werden kann. Dieser Parameter wird zurückgegeben, wenn der Rückgabewert von NotifyStableUnicastIpAddressTableERROR_IO_PENDING ist, was angibt, dass die E/A-Anforderung aussteht.

Rückgabewert

Wenn die Funktion sofort erfolgreich ist, wird der Rückgabewert NO_ERROR, und die stabile Unicast-IP-Tabelle wird im Table-Parameter zurückgegeben.

Wenn die E/A-Anforderung aussteht, gibt die Funktion ERROR_IO_PENDING zurück, und die Funktion, auf die der Parameter CallerCallback verweist, wird aufgerufen, wenn die E/A-Anforderung mit der stabilen Unicast-IP-Adresstabelle abgeschlossen wurde.

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 Table-Parameter ein NULL-Zeiger war, der NotificationHandle-Parameter ein NULL-Zeiger war oder der Family-Parameter weder AF_INET, AF_INET6 noch AF_UNSPEC war.
ERROR_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden.
Andere	Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

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

Wenn die NotifyStableUnicastIpAddressTable-Funktion sofort erfolgreich ist, wird der Rückgabewert NO_ERROR und die stabile Unicast-IP-Tabelle im Table-Parameter zurückgegeben. Die aufrufende Anwendung sollte den Speicher freigeben, auf den der Table-Parameter verweist, indem die FreeMibTable-Funktion verwendet wird, wenn die MIB_UNICASTIPADDRESS_TABLE Informationen nicht mehr benötigt werden.

Alle Unicast-IP-Adressen mit Ausnahme von Dial-on-Demand-Adressen werden nur dann als stabil betrachtet, wenn sie sich im bevorzugten Zustand befinden. Bei einem normalen Unicast-IP-Adresseintrag entspricht dies einem DadState-Member des MIB_UNICASTIPADDRESS_ROW für die ip-Adresse, die auf IpDadStatePreferred festgelegt ist. Jede Dial-on-Demand-Adresse definiert eine eigene Stabilitätsmetrik. Die einzige von dieser Funktion berücksichtigte Wähl-on-Demand-Adresse ist derzeit die Unicast-IP-Adresse, die vom Teredo-Client auf dem lokalen Computer verwendet wird.

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

Wenn NotifyStableUnicastIpAddressTable erfolgreich ist und NO_ERROR zurückgibt, gibt der Parameter Table die stabile Unicast-IP-Adresstabelle auf dem lokalen Computer zurück.

Die NotifyStableUnicastIpAddressTable-Funktion wird hauptsächlich von Anwendungen verwendet, die den Teredo-Client verwenden.

Wenn die von Teredo verwendete Unicast-IP-Adresse auf dem lokalen Computer, aber nicht im stabilen (qualifizierten) Zustand verfügbar ist, gibt NotifyStableUnicastIpAddressTable ERROR_IO_PENDING zurück, und die stabile Unicast-IP-Adresstabelle wird schließlich durch Aufrufen der Funktion im CallerCallback-Parameter zurückgegeben. Wenn die Teredo-Adresse nicht verfügbar oder im stabilen Zustand ist und sich die anderen Unicast-IP-Adressen in einem stabilen Zustand befinden, wird die Funktion im CallerCallback-Parameter nie aufgerufen.

Die im CallerCallback-Parameter angegebene Rückruffunktion sollte als Funktion des Typs VOID definiert werden. Die an die Rückruffunktion übergebenen Parameter umfassen Folgendes:

Parameter	BESCHREIBUNG
IN PVOID CallerContext	Der Parameter CallerContext , der bei der Registrierung für Benachrichtigungen an die Funktion NotifyStableUnicastIpAddressTable übergeben wird.
IN PMIB_UNICASTIPADDRESS_TABLE AddressTable	Ein Zeiger auf eine MIB_UNICASTIPADDRESS_TABLE , die die stabile Unicast-IP-Adresstabelle auf dem lokalen Computer enthält.

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

Der Speicher, auf den der AddressTable-Parameter verweist, der in einer Rückrufanzeige verwendet wird, wird vom Betriebssystem zugeordnet. Eine Anwendung, die eine Benachrichtigung empfängt, sollte den Speicher freigeben, auf den der AddressTable-Parameter verweist, indem die FreeMibTable-Funktion verwendet wird, wenn die MIB_UNICASTIPADDRESS_TABLE Informationen nicht mehr benötigt werden.

Sobald die NotifyStableUnicastIpAddressTable-Funktion aufgerufen wird, 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 automatisch die Registrierung für Änderungsbenachrichtigungen auf. Es wird weiterhin empfohlen, dass eine Anwendung die Registrierung von Änderungsbenachrichtigungen explizit aufhebt, bevor sie beendet wird.

Jede 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 Sie den NotificationHandle-Parameter , der von NotifyStableUnicastIpAddressTable zurückgegeben wird.

Eine Anwendung kann keinen Aufruf der CancelMibChangeNotify2-Funktion aus dem Kontext des Threads ausführen, 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 im Rahmen 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