NotifyStableUnicastIpAddressTable-Funktion (netioapi.h)
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.
[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 |
|---|---|
|
Es ist ein interner Fehler aufgetreten, bei dem ein ungültiges Handle aufgetreten ist. |
|
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. |
|
Es war nicht genügend Arbeitsspeicher vorhanden. |
|
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.
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.
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 |