WSAAddressToStringA-Funktion (winsock2.h)

Artikel
11/20/2024

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

Dies soll hauptsächlich für Anzeigezwecke verwendet werden. Wenn der Aufrufer erfordert, dass die Übersetzung von einem bestimmten Anbieter ausgeführt wird, sollte sie 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 im sockaddr- Struktur, auf die durch den parameter lpsaAddress verwiesen wurde. Der dwAddressLength Parameter kann mit verschiedenen Protokollen variieren.

[in, optional] lpProtocolInfo

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

[in, out] lpszAddressString

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

[in, out] lpdwAddressStringLength

Bei 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 einschließlich des NULL- Terminator 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 einen Wert von Null zurück. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und eine bestimmte Fehlernummer kann durch Aufrufen WSAGetLastErrorabgerufen werden.

Fehlercode	Bedeutung
WSAEFAULT-	Die angegebenen lpcsAddress, lpProtocolInfound lpszAddressString Parameter verweisen auf den Arbeitsspeicher, der nicht alle im Adressraum des Prozesses enthalten ist, oder der Puffer, auf den der lpszAddressString Parameter verweist, zu klein ist. Übergeben Sie einen größeren Puffer.
WSAEINVAL-	Ein ungültiger Parameter wurde übergeben. Dieser Fehler wird zurückgegeben, wenn der parameter lpsaAddress, dwAddressLengthoder lpdwAddressStringLength Parameter NULLsind. 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 Pufferspeicher verfügbar.
WSANOTINITIALISIERT	Die Winsock 2-DLL wurde nicht initialisiert. Die Anwendung muss zuerst WSAStartup- aufrufen, bevor Sie Windows Sockets-Funktionen aufrufen.

Bemerkungen

Die WSAAddressToString--Funktion stellt eine protokollunabhängige Adress-zu-Zeichenfolge-Übersetzung bereit. Die WSAAddressToString-funktion akzeptiert eine Socketadressenstruktur, auf die durch den lpsaAddress-Parameter verwiesen wird, und gibt einen Zeiger auf NULL--terminated-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 parameter lpsaAddress auf eine IPv4-Socketadresse verweist (die Adressfamilie ist AF_INET), wird die im Puffer zurückgegebene Adresszeichenfolge, auf die der lpszAddressString Parameter verweist, in punktierter Dezimalnotation wie in "192.168.168.16.0" angegeben, ein Beispiel für eine IPv4-Adresse in punktierter Dezimalnotation.

Wenn der parameter lpsaAddress auf eine IPv6-Socketadresse verweist (die Adressfamilie ist AF_INET6), wird die im Puffer zurückgegebene Adresszeichenfolge, auf die der lpszAddressString Parameter verweist, im Internetstandardformat angegeben. Die grundlegende Zeichenfolgendarstellung besteht aus 8 hexadezimalen Zahlen, die durch Doppelpunkte getrennt sind. Eine Zeichenfolge aufeinander folgender Nullnummern 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 lpszAddressString Parameter verweist, nicht groß genug ist, um die Zeichenfolgendarstellung der Socketadresse zu empfangen, gibt WSAAddressToStringWSAEFAULTzurü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 für die WSAAddressToString--Funktion installiert werden, um IPv6-Adressen zu unterstützen.

Windows Phone 8: Die WSAAddressToStringW--Funktion wird für Windows Phone Store-Apps unter 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 unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anmerkung

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
mindestens unterstützte Client-	Windows XP, Windows 8.1 [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winsock2.h
Library	Ws2_32.lib
DLL-	Ws2_32.dll