WSAAddressToStringW-Funktion (winsock2.h)

Artikel
08/27/2023

Die WSAAddressToString-Funktion konvertiert alle Komponenten einer sockaddr-Struktur in eine lesbare Zeichenfolgendarstellung der Adresse.

Dies ist vor allem für Anzeigezwecke vorgesehen. Wenn der Aufrufer erfordert, dass die Übersetzung von einem bestimmten Anbieter ausgeführt wird, sollte er die entsprechende WSAPROTOCOL_INFO-Struktur im lpProtocolInfo-Parameter bereitstellen.

Syntax

INT WSAAPI WSAAddressToStringW(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [in, out]      LPWSTR              lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

Parameter

[in] lpsaAddress

Ein Zeiger auf die sockaddr-Struktur , die in eine Zeichenfolge übersetzt werden soll.

[in] dwAddressLength

Die Länge der Adresse in Bytes in der sockaddr-Struktur , auf die der lpsaAddress-Parameter verweist. Der dwAddressLength-Parameter kann in der Größe mit unterschiedlichen Protokollen variieren.

[in, optional] lpProtocolInfo

Ein Zeiger auf die WSAPROTOCOL_INFO-Struktur für einen bestimmten Anbieter. Wenn der Parameter NULL ist, wird der Aufruf an den Anbieter des ersten Protokolls weitergeleitet, der die im lpsaAddress-Parameter angegebene Adressfamilie unterstützt.

[in, out] lpszAddressString

Ein Zeiger auf den Puffer, der die lesbare Adresszeichenfolge empfängt.

[in, out] lpdwAddressStringLength

Bei der Eingabe gibt dieser Parameter die Länge des Puffers an, auf den der lpszAddressString-Parameter verweist. Die Länge wird in Bytes für ANSI-Zeichenfolgen und in WCHARs für Unicode-Zeichenfolgen dargestellt. Bei der Ausgabe gibt dieser Parameter die Länge der Zeichenfolge zurück, einschließlich des NULL-Abschlusszeichens, der tatsächlich in den Puffer kopiert wurde, auf den der lpszAddressString-Parameter verweist. Wenn der angegebene Puffer nicht groß genug ist, schlägt die Funktion mit einem bestimmten Fehler von WSAEFAULT fehl, und dieser Parameter wird mit der erforderlichen Größe aktualisiert.

Rückgabewert

Wenn kein Fehler auftritt, gibt WSAAddressToString den Wert 0 zurück. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und eine bestimmte Fehlernummer kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSAEFAULT	Die angegebenen Parameter lpcsAddress, lpProtocolInfo und lpszAddressString verweisen auf Arbeitsspeicher, der sich nicht im Adressraum des Prozesses befindet, oder der Puffer, auf den der parameter lpszAddressString verweist, ist zu klein. Übergeben Sie einen größeren Puffer.
WSAEINVAL	Es wurde ein ungültiger Parameter übergeben. Dieser Fehler wird zurückgegeben, wenn der Parameter lpsaAddress, dwAddressLength oder lpdwAddressStringLengthNULL ist. Dieser Fehler wird auch zurückgegeben, wenn die angegebene Adresse keine gültige Socketadresse ist oder kein Transportanbieter die angegebene Adressfamilie unterstützt.
WSAENOBUFS	Es ist kein Pufferplatz verfügbar.
WSANOTINITIALISIERT	Die Winsock 2-DLL wurde nicht initialisiert. Die Anwendung muss zuerst WSAStartup aufrufen, bevor sie Windows Sockets-Funktionen aufruft.

Hinweise

Die WSAAddressToString-Funktion bietet eine protokollunabhängige Adress-zu-Zeichenfolge-Übersetzung. Die WSAAddressToString-Funktion nimmt eine Socketadressenstruktur an, auf die vom parameter lpsaAddress verwiesen wird, und gibt einen Zeiger auf null-beendete Zeichenfolge zurück, die die Socketadresse im lpszAddressString-Parameter darstellt. Während die inet_ntoa-Funktion nur mit IPv4-Adressen funktioniert, funktioniert die WSAAddressToString-Funktion mit jeder Socketadresse, die von einem Winsock-Anbieter auf dem lokalen Computer unterstützt wird, einschließlich IPv6-Adressen.

Wenn der lpsaAddress-Parameter auf eine IPv4-Socketadresse verweist (die Adressfamilie ist AF_INET), ist die im Puffer zurückgegebene Adresszeichenfolge, auf die der lpszAddressString-Parameter verweist, in gepunkteter Dezimalschreibweise wie in "192.168.16.0", ein Beispiel für eine IPv4-Adresse in gepunkteter Dezimalschreibweise.

Wenn der lpsaAddress-Parameter auf eine IPv6-Socketadresse verweist (die Adressfamilie ist AF_INET6), ist die im Puffer zurückgegebene Adresszeichenfolge, auf die der lpszAddressString-Parameter verweist, im 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.

Wenn die Länge des Puffers, auf den der parameter lpszAddressString verweist, nicht groß genug ist, um die Zeichenfolgendarstellung der Socketadresse zu empfangen, gibt WSAAddressToStringWSAEFAULT zurück.

Unterstützung für IPv6-Adressen, die die WSAAddressToString-Funktion verwenden, wurde unter Windows XP mit Service Pack 1 (SP1) und höher hinzugefügt. IPv6 muss auch auf dem lokalen Computer installiert sein, damit die WSAAddressToString-Funktion IPv6-Adressen unterstützt.

Windows Phone 8: Die WSAAddressToStringW-Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher unterstützt.

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

Hinweis

Der winsock2.h-Header definiert WSAAddressToString 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 nicht codierungsneutralem Code 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 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll