WSAAddressToStringA-Funktion (winsock2.h)
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 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 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 |
|---|---|
| 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. | |
| 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. | |
| Es ist kein Pufferplatz verfügbar. | |
| 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 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.
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
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP, Windows 8.1 [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 |