InetPtonW-Funktion (ws2tcpip.h)

Artikel
03/04/2024

Die InetPton-Funktion konvertiert eine IPv4- oder IPv6-Internetnetzwerkadresse in ihrer Standardtextdarstellungsform in die numerische Binärform. Die ANSI-Version dieser Funktion ist inet_pton.

Syntax

INT WSAAPI InetPtonW(
  [in]  INT    Family,
  [in]  PCWSTR pszAddrString,
  [out] PVOID  pAddrBuf
);

Parameter

[in] Family

Die Adressfamilie.

Mögliche Werte für die Adressfamilie sind 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. 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, muss der pszAddrString-Parameter auf eine Textdarstellung einer IPv4-Adresse verweisen, und der Parameter pAddrBuf gibt einen Zeiger auf eine IN_ADDR-Struktur zurück, die die IPv4-Adresse darstellt.
AF_INET6 23	Die IPv6-Adressfamilie (Internet Protocol Version 6). Wenn dieser Parameter angegeben wird, muss der pszAddrString-Parameter auf eine Textdarstellung einer IPv6-Adresse verweisen, und der Parameter pAddrBuf gibt einen Zeiger auf eine IN6_ADDR-Struktur zurück, die die IPv6-Adresse darstellt.

[in] pszAddrString

Ein Zeiger auf die NULL-Zeichenfolge, die die Textdarstellung der IP-Adresse enthält, die in numerische Binärform konvertiert werden soll.

Wenn der Family-ParameterAF_INET ist, muss der pszAddrString-Parameter auf eine Textdarstellung einer IPv4-Adresse in standardmäßiger punktierter Dezimalschreibweise verweisen.

Wenn der Family-ParameterAF_INET6 ist, muss der pszAddrString-Parameter auf eine Textdarstellung einer IPv6-Adresse in standardnotation verweisen.

[out] pAddrBuf

Ein Zeiger auf einen Puffer, in dem die numerische binäre Darstellung der IP-Adresse gespeichert werden soll. Die IP-Adresse wird in der Netzwerkbytereihenfolge zurückgegeben.

Wenn der Family-ParameterAF_INET ist, sollte dieser Puffer groß genug sein, um eine IN_ADDR-Struktur zu enthalten.

Wenn der Family-ParameterAF_INET6 ist, sollte dieser Puffer groß genug sein, um eine IN6_ADDR-Struktur zu enthalten.

Rückgabewert

Wenn kein Fehler auftritt, gibt die InetPton-Funktion den Wert 1 zurück, und der Puffer, auf den der pAddrBuf-Parameter verweist, enthält die binäre numerische IP-Adresse in Netzwerkbytereihenfolge.

Die InetPton-Funktion gibt den Wert 0 zurück, wenn der pAddrBuf-Parameter auf eine Zeichenfolge zeigt, die keine gültige IPv4-Dezimalzeichenfolge oder eine gültige IPv6-Adresszeichenfolge ist. Andernfalls wird der Wert -1 zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen der
WSAGetLastError für erweiterte Fehlerinformationen.

Wenn die Funktion einen Fehler aufweist, 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.
WSAEFAULT	Die Parameter pszAddrString oder pAddrBuf sind NULL oder nicht Teil des Benutzeradressraums.

Hinweise

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

Die InetPton-Funktion ermöglicht eine protokollunabhängige Konvertierung einer Internetnetzwerkadresse in ihrer Standardtextdarstellungsform in ihre numerische Binärform. Die InetPton-Funktion nimmt eine Textdarstellung einer Internetadresse an, auf die der pszAddrString-Parameter verweist, und gibt einen Zeiger auf die numerische binäre IP-Adresse im pAddrBuf-Parameter zurück. Während die funktion inet_addr nur mit IPv4-Adresszeichenfolgen funktioniert, funktioniert die InetPton-Funktion entweder mit IPv4- oder IPv6-Adresszeichenfolgen.

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

Die InetPton-Funktion erfordert nicht, dass die Windows Sockets-DLL geladen wird, um eine Textzeichenfolge, die eine IP-Adresse darstellt, in eine numerische binäre IP-Adresse zu konvertieren.

Wenn der angegebene Family-ParameterAF_INET ist, muss der pszAddrString-Parameter eine Textzeichenfolge einer IPv4-Adresse in gepunkteter Dezimalschreibweise wie in "192.168.16.0" zeigen, ein Beispiel für eine IPv4-Adresse in gepunkteter Dezimalschreibweise.

Wenn der angegebene Family-ParameterAF_INET6 ist, muss der pszAddrString-Parameter auf eine Textzeichenfolge einer IPv6-Adresse im Internetstandardformat verweisen. Die grundlegende Zeichenfolgendarstellung besteht aus 8 Hexadezimalzahlen, 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 in der IPv4-Art dotted-octet Notation dargestellt werden, wenn es sich bei der Adresse um eine IPv4-kompatible Adresse handelt.

Wenn UNICODE oder _UNICODE definiert ist, wird InetPton für InetPtonW, die Unicode-Version dieser Funktion, definiert. Der PszAddrString-Parameter ist für den PCWSTR-Datentyp definiert.

Wenn UNICODE oder _UNICODE nicht definiert ist, wird InetPton für InetPtonA, die ANSI-Version dieser Funktion, definiert. Die ANSI-Version dieser Funktion ist immer als inet_pton definiert. Der pszAddrString-Parameter ist für den PCSTR-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 RtlIpv4StringToAddress und RtlIpv4StringToAddressEx verwendet werden, um eine Textdarstellung einer IPv4-Adresse in der gepunkteten dezimalen Internet-Standardnotation in eine numerische binäre Adresse zu konvertieren, die als IN_ADDR-Struktur dargestellt wird. Unter Windows Vista und höher können die Funktionen RtlIpv6StringToAddress und RtlIpv6StringToAddressEx verwendet werden, um eine Zeichenfolgendarstellung einer IPv6-Adresse in eine numerische binäre IPv6-Adresse zu konvertieren, die als IN6_ADDR-Struktur dargestellt wird. Die RtlIpv6StringToAddressEx-Funktion ist flexibler, da sie auch eine Zeichenfolgendarstellung einer IPv6-Adresse, die eine Bereichs-ID und einen Port in Standardnotation enthalten kann, in eine numerische Binärform konvertiert.

Windows 8.1 und Windows Server 2012 R2: Die Funktion InetPtonW 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