WSAStringToAddressA-Funktion (winsock2.h)

Artikel
08/27/2023

Die WSAStringToAddress-Funktion konvertiert eine Netzwerkadresse in ihrer Standardtextpräsentationsform in ihre numerische binäre Form in einer sockaddr-Struktur , die für die Übergabe an Windows Sockets-Routinen geeignet ist, die eine solche Struktur verwenden.

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 null endende Zeichenfolge, die die Zu konvertierende Netzwerkadresse in Standardtextform enthält.

[in] AddressFamily

Die Adressfamilie der Netzwerkadresse, auf die der AddressString-Parameter verweist.

[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, der die angegebene AddressFamily unterstützt.

[out] lpAddress

Ein Zeiger auf einen Puffer, der mit einer sockaddr-Struktur für die Adresszeichenfolge gefüllt ist, 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 lpAddress-Parameter 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 Bytes 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 von WSAGetLastError abgerufen 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 einen sockaddr übersetzen. Weitere Informationen finden Sie im abschnitt "Hinweise".
WSANOTINITIALISIERT	Die WS2_32.DLL wurde nicht initialisiert. Die Anwendung muss zuerst WSAStartup aufrufen, bevor Windows Socket-Funktionen aufgerufen werden.
WSA_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang auszuführen.

Hinweise

Die WSAStringToAddress-Funktion konvertiert eine Netzwerkadresse in Standardtextform in ihre numerische Binärform in einer sockaddr-Struktur .

Fehlende Komponenten der Adresse werden nach Möglichkeit auf einen angemessenen Wert festgelegt. Beispielsweise wird eine fehlende Portnummer standardmäßig auf 0 (null) festgelegt. Wenn der Aufrufer möchte, dass die Übersetzung von einem bestimmten Anbieter durchgeführt wird, sollte er die entsprechende WSAPROTOCOL_INFO-Struktur im lpProtocolInfo-Parameter bereitstellen.

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

Unterstützung für IPv6-Adressen mit der WSAStringToAddress-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 WSAStringToAddress-Funktion IPv6-Adressen unterstützt.

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 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.

Hinweis

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


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