InetNtopW-Funktion (ws2tcpip.h)

Artikel
08/28/2023

Die InetNtop-Funktion konvertiert eine IPv4- oder IPv6-Internetnetzwerkadresse in eine Zeichenfolge im Internetstandardformat. Die ANSI-Version dieser Funktion ist inet_ntop.

Syntax

PCWSTR WSAAPI InetNtopW(
  [in]  INT        Family,
  [in]  const VOID *pAddr,
  [out] PWSTR      pStringBuf,
  [in]  size_t     StringBufSize
);

Parameter

[in] Family

Die Adressfamilie.

Mögliche Werte für die Adressfamilie sind in der Headerdatei Ws2def.h definiert. Beachten Sie, dass die Ws2def.h-Headerdatei automatisch in Winsock2.h enthalten ist und nie direkt verwendet werden sollte. 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.

Die derzeit unterstützten Werte sind AF_INET und AF_INET6.

Wert	Bedeutung
AF_INET 2	Die IPv4-Adressfamilie (Internet Protocol Version 4). Wenn dieser Parameter angegeben wird, gibt diese Funktion eine IPv4-Adresszeichenfolge zurück.
AF_INET6 23	Die IPv6-Adressfamilie (Internet Protocol Version 6). Wenn dieser Parameter angegeben wird, gibt diese Funktion eine IPv6-Adresszeichenfolge zurück.

[in] pAddr

Ein Zeiger auf die IP-Adresse im Netzwerkbyte, um in eine Zeichenfolge zu konvertieren.

Wenn der Family-ParameterAF_INET ist, muss der pAddr-Parameter auf eine IN_ADDR-Struktur mit der zu konvertierenden IPv4-Adresse verweisen.

Wenn der Family-ParameterAF_INET6 ist, muss der pAddr-Parameter auf eine IN6_ADDR-Struktur mit der zu konvertierenden IPv6-Adresse verweisen.

[out] pStringBuf

Ein Zeiger auf einen Puffer, in dem die NULL-beendete Zeichenfolgendarstellung der IP-Adresse gespeichert werden soll.

Für eine IPv4-Adresse sollte dieser Puffer groß genug sein, um mindestens 16 Zeichen aufzunehmen.

Für eine IPv6-Adresse sollte dieser Puffer groß genug sein, um mindestens 46 Zeichen aufzunehmen.

[in] StringBufSize

Bei der Eingabe die Länge des Puffers in Zeichen, auf die der pStringBuf-Parameter verweist.

Rückgabewert

Wenn kein Fehler auftritt, gibt die InetNtop-Funktion einen Zeiger auf einen Puffer zurück, der die Zeichenfolgendarstellung der IP-Adresse im Standardformat enthält.

Andernfalls wird ein Wert von NULL zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen des
WSAGetLastError für erweiterte Fehlerinformationen.

Wenn die Funktion fehlschlägt, kann der von WSAGetLastError zurückgegebene erweiterte Fehlercode einer der folgenden Werte sein.

Fehlercode	Bedeutung
WSAEAFNOSUPPORT	Die im Family-Parameter angegebene Adressfamilie wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der angegebene Family-Parameter nicht AF_INET oder AF_INET6 wurde.
ERROR_INVALID_PARAMETER	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein NULL-Zeiger im pStringBuf übergeben wird oder der StringBufSize-Parameter 0 ist. Dieser Fehler wird auch zurückgegeben, wenn die Länge des Puffers, auf den der pStringBuf-Parameter verweist, nicht groß genug ist, um die Zeichenfolgendarstellung der IP-Adresse zu empfangen.

Hinweise

Die InetNtop-Funktion wird unter Windows Vista und höher unterstützt.

Die InetNtop-Funktion bietet eine protokollunabhängige Adress-zu-Zeichenfolge-Übersetzung. Die InetNtop-Funktion übernimmt eine durch den pAddr-Parameter angegebene Internetadressenstruktur und gibt eine NULL-beendete Zeichenfolge zurück, die die IP-Adresse darstellt. Während die inet_ntoa-Funktion nur mit IPv4-Adressen funktioniert, funktioniert die InetNtop-Funktion entweder mit IPv4- oder IPv6-Adressen.

Die ANSI-Version dieser Funktion ist inet_ntop , wie in RFC 2553 definiert. Weitere Informationen finden Sie unter RFC 2553 auf der IETF-Website.

Die InetNtop-Funktion erfordert nicht, dass die Windows Sockets-DLL geladen wird, um die IP-Adresse in die Zeichenfolge zu konvertieren.

Wenn der angegebene Family-ParameterAF_INET ist, muss der pAddr-Parameter auf eine IN_ADDR Struktur mit der zu konvertierenden IPv4-Adresse verweisen. Die im Puffer zurückgegebene Adresszeichenfolge, auf die der pStringBuf-Parameter verweist, ist in gepunkteter Dezimalschreibweise wie in "192.168.16.0", ein Beispiel für eine IPv4-Adresse in gepunkteter Dezimalschreibweise.

Wenn der angegebene Family-ParameterAF_INET6 ist, muss der pAddr-Parameter auf eine IN6_ADDR-Struktur mit der zu konvertierenden IPv6-Adresse verweisen. Die Adresszeichenfolge, die im Puffer zurückgegeben wird, auf den der pStringBuf-Parameter verweist, hat das Internetstandardformat. Die grundlegende Zeichenfolgendarstellung besteht aus 8 hexadezimalen Zahlen, die durch Doppelpunkte getrennt sind. Eine Zeichenfolge mit aufeinanderfolgenden Nullzahlen wird durch einen Doppelpunkt ersetzt. In der Zeichenfolgendarstellung der IPv6-Adresse kann nur ein Doppelpunkt vorhanden sein. Die letzten 32 Bits werden in IPv4-Style dotted-octet notation dargestellt, wenn es sich bei der Adresse um eine IPv4-kompatible Adresse handelt.

Wenn die Länge des Puffers, auf den der pStringBuf-Parameter verweist, nicht groß genug ist, um die Zeichenfolgendarstellung der IP-Adresse zu empfangen, gibt InetNtop ERROR_INVALID_PARAMETER zurück.

Wenn UNICODE oder _UNICODE definiert ist, wird InetNtop als InetNtopW definiert, die Unicode-Version dieser Funktion. Der pStringBuf-Parameter ist für den PSTR-Datentyp definiert.

Wenn UNICODE oder _UNICODE nicht definiert ist, wird InetNtop für InetNtopA definiert, die ANSI-Version dieser Funktion. Die ANSI-Version dieser Funktion ist immer als inet_ntop definiert. Der pStringBuf-Parameter wird für den PWSTR-Datentyp definiert.

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

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

Unter Windows Vista und höher können die Funktionen RtlIpv4AddressToString und RtlIpv4AddressToStringEx verwendet werden, um eine als IN_ADDR Struktur dargestellte IPv4-Adresse in eine Zeichenfolgendarstellung einer IPv4-Adresse in der Internetstandard-Punkt-Dezimalschreibweise zu konvertieren. Unter Windows Vista und höher können die Funktionen RtlIpv6AddressToString und RtlIpv6AddressToStringEx verwendet werden, um eine als IN6_ADDR Struktur dargestellte IPv6-Adresse in eine Zeichenfolgendarstellung einer IPv6-Adresse zu konvertieren. Die RtlIpv6AddressToStringEx-Funktion ist flexibler, da sie auch eine IPv6-Adresse, Bereichs-ID und einen Port in eine IPv6-Zeichenfolge im Standardformat konvertiert.

Windows 8.1 und Windows Server 2012 R2: Die InetNtopW-Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	ws2tcpip.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll