WSAAddressToStringA-Funktion (winsock2.h)

Artikel
03/04/2024

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

Dies ist hauptsächlich 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 WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               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 Byte 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 parameter lpszAddressString 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 einschließlich des NULL-Abschlusszeichens zurück, 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 (null) 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 die Parameter lpsaAddress, dwAddressLength oder lpdwAddressStringLengthNULL sind. 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 Windows Sockets-Funktionen aufgerufen werden.

Hinweise

Die WSAAddressToString-Funktion stellt eine protokollunabhängige Übersetzung von Adressen in Zeichenfolgen bereit. Die WSAAddressToString-Funktion verwendet eine Socketadressenstruktur, auf die der lpsaAddress-Parameter verweist, und gibt einen Zeiger auf null-terminierte Zeichenfolge zurück, der die Socketadresse im lpszAddressString-Parameter darstellt. Während die funktion inet_ntoa nur mit IPv4-Adressen funktioniert, funktioniert die WSAAddressToString-Funktion mit allen Socketadressen, die von einem Winsock-Anbieter auf dem lokalen Computer unterstützt werden, 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 dezimaler Notation 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), hat die im Puffer zurückgegebene Adresszeichenfolge, auf die der parameter lpszAddressString verweist, im Internetstandardformat. Die grundlegende Zeichenfolgendarstellung besteht aus 8 Hexadezimalzahlen, 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 mithilfe der WSAAddressToString-Funktion wurde unter Windows XP mit Service Pack 1 (SP1) und höher hinzugefügt. IPv6 muss auch auf dem lokalen Computer installiert werden, 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 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

Anforderung	Wert
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