RtlIpv6StringToAddressA-Funktion (ip2string.h)

Artikel
01/27/2024

Die RtlIpv6StringToAddress-Funktion konvertiert eine Zeichenfolgendarstellung einer IPv6-Adresse in eine binäre IPv6-Adresse.

Syntax

NTSYSAPI NTSTATUS RtlIpv6StringToAddressA(
  [in]  PCSTR    S,
  [out] PCSTR    *Terminator,
  [out] in6_addr *Addr
);

Parameter

[in] S

Ein Zeiger auf einen Puffer, der die NULL-beendete Zeichenfolgendarstellung der IPv6-Adresse enthält.

[out] Terminator

Ein Parameter, der einen Zeiger auf das Zeichen empfängt, das die konvertierte Zeichenfolge beendet hat. Dies kann vom Aufrufer verwendet werden, um weitere Informationen aus der Zeichenfolge zu extrahieren.

[out] Addr

Ein Zeiger, in dem die binäre Darstellung der IPv6-Adresse gespeichert werden soll.

Rückgabewert

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

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn die Zeichenfolge, auf die der S-Parameter verweist, keine ordnungsgemäße Zeichenfolgendarstellung einer IPv6-Adresse enthielt. Dieser Fehlercode ist in der Ntstatus.h-Headerdatei definiert.
Andere	Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die RtlIpv6StringToAddress-Funktion wird verwendet, um eine Zeichenfolgendarstellung der IPv6-Adresse in eine IPv6-Adresse zu konvertieren, die in Netzwerkreihenfolge zurückgegeben wird (von links nach rechts sortierte Bytes).

RtlIpv6StringToAddress ist eine Komfortfunktion, die nicht erfordert, dass die Windows Sockets-DLL geladen werden muss, um auf eine in Windows Sockets bereitgestellte Funktion zuzugreifen, um eine Konvertierung von Zeichenfolgen in IP-Adressen durchzuführen.

Die Zeichenfolge, auf die der S-Parameter verweist, muss im Format für eine IPv6-Adresszeichenfolge dargestellt werden. Die grundlegende Zeichenfolgendarstellung einer IPv6-Adresse besteht aus 8 hexadezimalen Zahlen, die durch Doppelpunkte getrennt sind. Eine Zeichenfolge mit aufeinanderfolgenden Nullzahlen kann durch einen Doppelkolon ersetzt werden. In der Zeichenfolgendarstellung der IPv6-Adresse kann nur ein Doppelpunkt vorhanden sein. Die letzten 32 Bits können im IPv4-Stil als dotted-octet-Notation dargestellt werden, wenn es sich bei der Adresse um eine IPv4-kompatible Adresse, eine IPv4-zugeordnete IPv6-Adresse oder eine ISATAP-Adresse handelt. Weitere Informationen finden Sie im Abschnitt 5 von RFC 5942 , der von der IETF veröffentlicht wurde.

Bei Erfolg zeigt der Terminator-Parameter auf das Zeichen, das die konvertierte Zeichenfolge beendet hat. Dadurch kann eine Anwendung eine Zeichenfolge, die die IP-Adresse und zusätzliche Informationen enthält, an die RtlIpv6StringToAddress-Funktion übergeben und dann die verbleibenden Informationen analysieren.

Hinweis Einige falsch formatierte IPv6-Adressen (z. B. ::::) beginnen mit einer gültigen IPv6-Adresse. Die RtlIpv6StringToAddress-Funktion gibt erfolgreich zurück, nachdem der gültige Teil der IPv6-Adresse als Doppelpunkt (::). Das Abschlusszeichen zeigt dann auf den dritten Doppelpunkt. Um zu überprüfen, ob die gesamte übergebene Zeichenfolge eine gültige IPv6-Adresse ist, müssen Sie sicherstellen, dass der Abschluss auf das richtige Zeichen zeigt. Wenn der S-Parameter nur eine IPv6-Adresse enthält, sollte der Abschlusszeichen auf das NULL-Zeichen am Ende der Zeichenfolge zeigen.

Wenn entweder UNICODE oder _UNICODE definiert ist, wird RtlIpv6StringToAddress für RtlIpv6StringToAddressW, die Unicode-Version dieser Funktion, definiert. Die Parameter S und Terminator sind für den PCWSTR-Datentyp definiert.

Wenn sowohl UNICODE als auch _UNICODE nicht definiert sind, wird RtlIpv6StringToAddress für RtlIpv6StringToAddressA, die ANSI-Version dieser Funktion, definiert. Die Parameter S und Terminator sind für den PCSTR-Datentyp definiert.

Die IN6_ADDR-Struktur ist in der Headerdatei In6addr.h definiert.

Eine Importbibliothek, die die RtlIpv6StringToAddress-Funktion enthält, ist nicht im Microsoft Windows Software Development Kit (SDK) enthalten, das für Windows Vista veröffentlicht wurde. Die RtlIpv6StringToAddress-Funktion ist in der Ntdll.lib-Importbibliothek enthalten, die im Windows Driver Kit (WDK) enthalten ist. Eine Anwendung kann auch die Funktionen GetModuleHandle und GetProcAddress verwenden, um den Funktionszeiger aus dem Ntdll.dll abzurufen und diese Funktion aufzurufen.

Hinweis

Der Ip2string.h-Header definiert RtlIpv6StringToAddress als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	ip2string.h (include Mstcpip.h, Ip2string.h)
Bibliothek	ntdll.lib
DLL	ntdll.dll