WSAStringToAddressA-Funktion (winsock2.h)

Artikel
11/20/2024

Die WSAStringToAddress-Funktion wandelt eine Netzwerkadresse in der Standardtextpräsentationsform in die numerische Binäre Form in einer sockaddr--Struktur um, die für die Übergabe an Windows Sockets-Routinen geeignet ist, die eine solche Struktur übernehmen.

Syntax

INT WSAAPI WSAStringToAddressA(
  [in]           LPSTR               AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [out]          LPSOCKADDR          lpAddress,
  [in, out]      LPINT               lpAddressLength
);

Parameter

[in] AddressString

Ein Zeiger auf die mit Null beendete Zeichenfolge, die die Netzwerkadresse in Standardtextform enthält, die konvertiert werden soll.

[in] AddressFamily

Die Adressfamilie der Netzwerkadresse, auf die durch den parameter AddressString verwiesen wird.

[in, optional] lpProtocolInfo

Die WSAPROTOCOL_INFO Struktur, die dem zu verwendenden Anbieter zugeordnet ist. Wenn dies NULL-ist, wird der Aufruf an den Anbieter des ersten Protokolls weitergeleitet, das die angegebene AddressFamily-unterstützt.

[out] lpAddress

Ein Zeiger auf einen Puffer, der mit einem Sockaddr gefüllt ist, Struktur für die Adresszeichenfolge, wenn die Funktion erfolgreich ist.

[in, out] lpAddressLength

Ein Zeiger auf die Länge des Puffers in Bytes, auf den der lpAddress-Parameter verweist. Wenn der Funktionsaufruf erfolgreich ist, gibt dieser Parameter einen Zeiger auf die Größe der sockaddr Struktur zurück, die im parameter lpAddress zurückgegeben wird. 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 in Byte aktualisiert.

Rückgabewert

Der Rückgabewert für WSAStringToAddress ist null, wenn der Vorgang erfolgreich war. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und eine bestimmte Fehlernummer kann durch Aufrufen WSAGetLastErrorabgerufen werden.

Fehlercode	Bedeutung
WSAEFAULT-	Der Puffer, auf den der lpAddress-Parameter verweist, ist zu klein. Übergeben Sie einen größeren Puffer.
WSAEINVAL-	Die Funktionen konnten die Zeichenfolge nicht in eine sockaddr-übersetzen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
WSANOTINITIALISIERT	Die WS2_32.DLL wurde nicht initialisiert. Die Anwendung muss zuerst WSAStartup- aufrufen, bevor Sie Windows Socket-Funktionen aufrufen.
WSA_NOT_ENOUGH_MEMORY	Zum Ausführen des Vorgangs war nicht genügend Arbeitsspeicher vorhanden.

Bemerkungen

Die WSAStringToAddress-Funktion wandelt eine Netzwerkadresse in Standardtextform in die numerische Binärform in einer sockaddr--Struktur um.

Wenn möglich, werden alle fehlenden Komponenten der Adresse auf einen angemessenen Wert festgelegt. Eine fehlende Portnummer wird z. B. standardmäßig auf Null festgelegt. Wenn der Aufrufer die Übersetzung von einem bestimmten Anbieter ausführen möchte, sollte er die entsprechende WSAPROTOCOL_INFO Struktur im lpProtocolInfo Parameter bereitstellen.

Die WSAStringToAddress--Funktion schlägt fehl (und gibt WSAEINVAL zurück), wenn das sin_family Element der SOCKADDR_IN-Struktur, das im parameter lpAddress in Form einer sockaddr--Struktur übergeben wird, nicht auf AF_INET oder AF_INET6 festgelegt ist.

Unterstützung für IPv6-Adressen mithilfe der WSAStringToAddress--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 WSAStringToAddress Funktion installiert werden, um IPv6-Adressen zu unterstützen.

Windows Phone 8: Diese 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: Diese 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 WSAStringToAddress 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 8.1, Windows Vista [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