RtlIpv4StringToAddressA-Funktion (ip2string.h)

Artikel
01/27/2024

Die RtlIpv4StringToAddress-Funktion konvertiert eine Zeichenfolgendarstellung einer IPv4-Adresse in eine binäre IPv4-Adresse.

Syntax

NTSYSAPI NTSTATUS RtlIpv4StringToAddressA(
  [in]  PCSTR   S,
  [in]  BOOLEAN Strict,
  [out] PCSTR   *Terminator,
  [out] in_addr *Addr
);

Parameter

[in] S

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

[in] Strict

Ein -Wert, der angibt, ob die Zeichenfolge eine IPv4-Adresse sein muss, die in strikter vierteiliger gepunkteter Dezimalschreibweise dargestellt wird. Wenn dieser Parameter TRUE ist, muss die Zeichenfolge mit vier Teilen gepunktet-dezimal sein. Wenn dieser Parameter FALSE ist, sind alle vier möglichen Formen mit dezimaler, oktaler oder hexadezimaler Notation zulässig. Weitere Informationen finden Sie im Abschnitt Hinweise.

[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 IPv4-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 der Strict-Parameter auf TRUE festgelegt wurde, aber die Zeichenfolge, auf die der S-Parameter verweist, keine vierteilige gepunktete Dezimalzeichenfolgendarstellung einer IPv4-Adresse enthielt. Dieser Fehler wird auch zurückgegeben, wenn die Zeichenfolge, auf die der S-Parameter verweist, keine ordnungsgemäße Zeichenfolgendarstellung einer IPv4-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.

Rückgabecode

Beschreibung

STATUS_INVALID_PARAMETER

Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn der Strict-Parameter auf TRUE festgelegt wurde, aber die Zeichenfolge, auf die der S-Parameter verweist, keine vierteilige gepunktete Dezimalzeichenfolgendarstellung einer IPv4-Adresse enthielt. Dieser Fehler wird auch zurückgegeben, wenn die Zeichenfolge, auf die der S-Parameter verweist, keine ordnungsgemäße Zeichenfolgendarstellung einer IPv4-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 RtlIpv4StringToAddress-Funktion wird verwendet, um eine Zeichenfolgendarstellung der IPv4-Adresse in eine IPv4-Adresse zu konvertieren, die in Netzwerkreihenfolge zurückgegeben wird (byte von links nach rechts sortiert).

RtlIpv4StringToAddress 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.

Wenn der Strict-Parameter auf TRUE festgelegt ist, muss die Zeichenfolge, auf die der S-Parameter verweist, in strikter punktierter dezimaler Schreibweise enthalten sein. Dieses strikte Format erfordert, dass vier Teile angegeben werden. Jeder Teil wird als dezimales Byte von Daten interpretiert und den vier Bytes einer IPv4-Adresse von links nach rechts zugewiesen.

Wenn der Strict-Parameter auf FALSE festgelegt ist, kann die Zeichenfolge, auf die der S-Parameter verweist, in einem der verschiedenen möglichen Formate vorliegen. Wenn der Puffer, auf den der S-Parameter verweist, eine dreiteilige Adresszeichenfolge enthält, wird der letzte Teil als 16-Bit-Menge interpretiert und in die meisten zwei Bytes der Netzwerkadresse rechts platziert. Dadurch ist das dreiteilige Adressformat für die Angabe von Netzwerkadressen der Klasse B als "128.net.host" praktisch. Wenn der Puffer, auf den der S-Parameter verweist, eine zweiteilige Adresszeichenfolge enthält, wird der letzte Teil als 24-Bit-Menge interpretiert und in die meisten drei Bytes der Netzwerkadresse rechts platziert. Dadurch ist das zweiteilige Adressformat für die Angabe von Netzwerkadressen der Klasse A als "net.host" praktisch. Wenn der Puffer, auf den der S-Parameter verweist, nur eine einteilige Adresszeichenfolge enthält, wird der Wert ohne Byte-Neuanordnung direkt in der Netzwerkadresse gespeichert.

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

Wenn unicode oder _UNICODE definiert ist, wird RtlIpv4StringToAddress für RtlIpv4StringToAddressW, die Unicode-Version dieser Funktion, definiert. Der S-Parameter wird für den PCWSTR-Datentyp und der Terminator-Parameter für den LPCWSTR-Datentyp definiert.

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

Die IN_ADDR-Struktur ist in der Headerdatei Inaddr.h definiert.

Eine Importbibliothek, die die RtlIpv4StringToAddress-Funktion enthält, ist nicht im Microsoft Windows Software Development Kit (SDK) enthalten, das für Windows Vista veröffentlicht wurde. Die RtlIpv4StringToAddress-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 RtlIpv4StringToAddress 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