CreateUnicastIpAddressEntry-Funktion

Artikel
05/03/2024

Die CreateUnicastIpAddressEntry-Funktion fügt einen neuen Unicast-IP-Adresseintrag auf dem lokalen Computer hinzu.

Syntax

NETIOAPI_API CreateUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

Parameter

Zeile [in]
Ein Zeiger auf einen MIB_UNICASTIPADDRESS_ROW Struktureintrag für einen Unicast-IP-Adresseintrag.

Rückgabewert

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

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein NULL-Zeiger im Row-Parameter übergeben wird, das Address-Element der MIB_UNICASTIPADDRESS_ROW Struktur, auf die der Row-Parameter verweist, nicht auf eine gültige Unicast-IPv4- oder IPv6-Adresse festgelegt wurde, oder die Elemente "InterfaceLuid" und "InterfaceIndex" der MIB_UNICASTIPADDRESS_ROW Struktur wurden nicht angegeben. Dieser Fehler wird auch für andere Fehler in den Werten zurückgegeben, die für Elemente in der MIB_UNICASTIPADDRESS_ROW-Struktur festgelegt sind. Zu diesen Fehlern gehören die folgenden Situationen: Das ValidLifetime-Element ist kleiner als das PreferredLifetime-Mitglied . Das PrefixOrigin-Element ist auf "IpPrefixOriginUnchanged " festgelegt, und das SuffixOrigin ist nicht auf "IpSuffixOriginUnchanged" festgelegt. Das PrefixOrigin-Element ist nicht auf "IpPrefixOriginUnchanged " festgelegt, und " SuffixOrigin " ist auf "IpSuffixOriginUnchanged" festgelegt. Das PrefixOrigin-Element wird nicht auf einen Wert aus der NL_PREFIX_ORIGIN-Aufzählung festgelegt. Das SuffixOrigin-Element wird nicht auf einen Wert aus der NL_SUFFIX_ORIGIN-Aufzählung festgelegt. Das OnLinkPrefixLength-Element wird auf einen Wert festgelegt, der größer als die LÄNGE der IP-Adresse in Bits ist (32 für eine Unicast-IPv4-Adresse oder 128 für eine Unicast-IPv6-Adresse). Mögliche Werte der enumerationen NL_PREFIX_ORIGIN und NL_SUFFIX_ORIGIN finden Sie unter MIB_UNICASTIPADDRESS_ROW.
STATUS_NOT_FOUND	Die angegebene Schnittstelle kann nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn die Funktion die Netzwerkschnittstelle nicht finden kann, die vom InterfaceLuid - oder InterfaceIndex-Element der MIB_UNICASTIPADDRESS_ROW Struktur angegeben wird, auf die der Row-Parameter verweist.
STATUS_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn sich kein IPv4-Stapel auf dem lokalen Computer befindet und eine IPv4-Adresse im Adresselement der MIB_UNICASTIPADDRESS_ROW Struktur angegeben wurde, auf die der Row-Parameter verweist, oder wenn sich kein IPv6-Stapel auf dem lokalen Computer befindet und eine IPv6-Adresse im Address-Element angegeben wurde.
ERROR_OBJECT_ALREADY_EXISTS	Das Objekt ist bereits vorhanden. Dieser Fehler wird zurückgegeben, wenn das Address-Element der MIB_UNICASTIPADDRESS_ROW Struktur, auf die der Row-Parameter verweist, ein Duplikat einer vorhandenen Unicast-IP-Adresse auf der Schnittstelle ist, die vom InterfaceLuid - oder InterfaceIndex-Element des MIB_UNICASTIPADDRESS_ROW angegeben wird.
Andere	Verwenden Sie die FormatMessage-Funktion, um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Verwenden Sie die InitializeUnicastIpAddressEntry-Funktion , um die Member eines MIB_UNICASTIPADDRESS_ROW Struktureintrags mit Standardwerten zu initialisieren. Ein Treiber kann dann die Elemente im MIB_UNICASTIPADDRESS_ROW Eintrag ändern, den er ändern möchte, und dann die CreateUnicastIpAddressEntry-Funktion aufrufen.

Bei der Eingabe muss der Treiber die folgenden Elemente der MIB_UNICASTIPADDRESS_ROW Struktur initialisieren, auf die der Row-Parameter verweist.

Adresse
Festlegen auf eine gültige Unicast-IPv4- oder IPv6-Adresse und -Familie.
InterfaceLuid oder InterfaceIndex
Diese Member werden in der Reihenfolge verwendet, die zuvor aufgeführt ist. Wenn "InterfaceLuid " angegeben ist, wird dieses Element verwendet, um die Schnittstelle zu bestimmen, der die Unicast-IP-Adresse hinzugefügt werden soll. Wenn kein Wert für das InterfaceLuid-Element festgelegt wurde (der Wert dieses Elements wurde auf Null gesetzt), wird InterfaceIndex als Nächstes verwendet, um die Schnittstelle zu bestimmen.

Wenn das OnLinkPrefixLength-Element der MIB_UNICASTIPADDRESS_ROW-Struktur, auf die der Row-Parameter verweist, auf 255 festgelegt ist, fügt CreateUnicastIpAddressEntry die neue Unicast-IP-Adresse hinzu, wobei das OnLinkPrefixLength-Element auf die Länge der IP-Adresse festgelegt ist. Für eine Unicast-IPv4-Adresse ist die OnLinkPrefixLength auf 32 festgelegt, und " OnLinkPrefixLength " ist für eine Unicast-IPv6-Adresse auf 128 festgelegt. Wenn diese Einstellung zu einer falschen Subnetzmaske für eine IPv4-Adresse oder das falsche Verknüpfungspräfix für eine IPv6-Adresse führen würde, sollte der Treiber das OnLinkPrefixLength-Element auf den richtigen Wert festlegen, bevor CreateUnicastIpAddressEntry aufgerufen wird.

Wenn eine Unicast-IP-Adresse erstellt wird, deren OnLinkPrefixLength-Member falsch festgelegt wurde, kann Ihr Treiber die IP-Adresse ändern, indem "SetUnicastIpAddressEntry" aufgerufen wird, wobei das OnLinkPrefixLength-Element auf den richtigen Wert festgelegt ist.

Die Elemente "DadState", "ScopeId" und "CreationTimeStamp " der MIB_UNICASTIPADDRESS_ROW Struktur, auf die der Row-Parameter verweist, werden ignoriert, wenn die CreateUnicastIpAddressEntry-Funktion aufgerufen wird. Diese Member werden vom Netzwerkstapel festgelegt. Das ScopeId-Element wird automatisch von der Schnittstelle bestimmt, auf der die Adresse hinzugefügt wird.

Die CreateUnicastIpAddressEntry-Funktion schlägt fehl, wenn die unicast-IP-Adresse, die im Address-Element der MIB_UNICASTIPADDRESS_ROW Struktur übergeben wird, auf die der Row-Parameter verweist, ein Duplikat einer vorhandenen Unicast-IP-Adresse auf der Schnittstelle ist. Beachten Sie, dass Ihr Treiber eine Loopback-IP-Adresse nur mithilfe der CreateUnicastIpAddressEntry-Funktion zu einer Loopbackschnittstelle hinzufügen kann.

Die unicast-IP-Adresse, die im Adresselement der MIB_UNICASTIPADDRESS_ROW Struktur übergeben wird, auf die der Row-Parameter verweist, kann nicht sofort verwendet werden. Die IP-Adresse kann verwendet werden, nachdem der Prozess zur Erkennung doppelter Adressen erfolgreich abgeschlossen wurde. Es kann mehrere Sekunden dauern, bis der Vorgang zur Erkennung doppelter Adressen abgeschlossen ist, da IP-Pakete gesendet werden müssen und potenzielle Antworten abgewartet werden müssen. Bei IPv6 dauert der Erkennungsprozess doppelter Adressen in der Regel etwa 1 Sekunde. Für IPv4 dauert der Erkennungsprozess doppelter Adressen in der Regel etwa 3 Sekunden.

Nachdem ein Treiber die CreateUnicastIpAddressEntry-Funktion aufgerufen hat, kann er mithilfe der folgenden Methoden ermitteln, ob eine IP-Adresse weiterhin verwendet werden kann:

Verwenden der Abfrage und der GetUnicastIpAddressEntry-Funktion
Nachdem der Aufruf der CreateUnicastIpAddressEntry-Funktion erfolgreich zurückgegeben wurde, anhalten Sie 1 bis 3 Sekunden (je nachdem, ob eine IPv6- oder IPv4-Adresse erstellt wird), um Zeit für den erfolgreichen Abschluss des Vorgangs zur Erkennung von Duplizierungsadressen zu ermöglichen. Rufen Sie dann GetUnicastIpAddressEntry auf, um die aktualisierte MIB_UNICASTIPADDRESS_ROW Struktur abzurufen und den Wert des DadState-Elements zu untersuchen. Wenn der Wert des DadState-Elements auf "IpDadStatePreferred" festgelegt ist, kann die IP-Adresse jetzt verwendet werden. Wenn der Wert des DadState-Elements auf "IpDadStateTentative " festgelegt ist, wurde die Erkennung doppelter Adressen noch nicht abgeschlossen. Rufen Sie in diesem Fall die GetUnicastIpAddressEntry-Funktion alle 0,5 Sekunden erneut auf, während der DadState-Member weiterhin auf "IpDadStateTentative" festgelegt ist. Wenn der Wert des DadState-Elements mit einem anderen Wert als IpDadStatePreferred oder IpDadStateTentative zurückgegeben wird, ist die Erkennung doppelter Adressen fehlgeschlagen, und die IP-Adresse kann nicht verwendet werden.
Rufen Sie eine der IP-Hilfsfunktionen NotifyXxx auf, um eine asynchrone Benachrichtigung einzurichten, wenn sich eine Adresse ändert.
Nachdem der Aufruf der CreateUnicastIpAddressEntry-Funktion erfolgreich zurückgegeben wurde, rufen Sie die NotifyUnicastIpAddressChange-Funktion auf, um den Treiber zu registrieren, um über Änderungen an IPv6- oder IPv4-Unicast-IP-Adressen benachrichtigt zu werden, abhängig vom Typ der erstellten IP-Adresse. Wenn eine Benachrichtigung für die ip-Adresse empfangen wird, die erstellt wird, rufen Sie die GetUnicastIpAddressEntry-Funktion auf, um den DadState-Member abzurufen. Wenn der Wert des DadState-Elements auf "IpDadStatePreferred" festgelegt ist, kann die IP-Adresse jetzt verwendet werden. Wenn der Wert des DadState-Elements auf "IpDadStateTentative " festgelegt ist, wurde die Erkennung doppelter Adressen noch nicht abgeschlossen, und der Treiber muss auf zukünftige Benachrichtigungen warten. Wenn der Wert des DadState-Elements mit einem anderen Wert als IpDadStatePreferred oder IpDadStateTentative zurückgegeben wird, ist die Erkennung doppelter Adressen fehlgeschlagen, und die IP-Adresse kann nicht verwendet werden.

Wenn während des Erkennungsprozesses doppelter Adressen das Medium getrennt und dann erneut verbunden wird, wird der Erkennungsprozess für doppelte Adressen neu gestartet. Die Zeit zum Abschließen des Prozesses kann also über den typischen 1-Sekunden-Wert für IPv6 oder 3 Sekunden für IPv4 hinausgehen.

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