WSAAsyncGetHostByName-Makro (wsipv6ok.h)

Artikel
08/28/2023

Die WSAAsyncGetHostByName-Funktion ruft asynchron Hostinformationen ab, die einem Hostnamen entsprechen.

Hinweis Die WSAAsyncGetHostByName-Funktion ist nicht für die parallele Auflösung mehrerer Namen konzipiert. Daher sollten Anwendungen, die mehrere Anforderungen ausgeben, nicht erwarten, dass sie gleichzeitig ausgeführt werden. Alternativ können Anwendungen einen anderen Thread starten und die getaddrinfo-Funktion verwenden, um Namen in einer unabhängigen IP-Version aufzulösen. Entwickler, die Windows Sockets 2-Anwendungen erstellen, werden dringend aufgefordert, die getaddrinfo-Funktion zu verwenden, um einen reibungslosen Übergang zur IPv6-Kompatibilität zu ermöglichen.

Syntax

void WSAAsyncGetHostByName(
  [in]   a,
  [in]   b,
  [in]   c,
  [out]  d,
  [in]   e
);

Parameter

[in] a

Handle des Fensters, das eine Nachricht empfängt, wenn die asynchrone Anforderung abgeschlossen ist.

[in] b

Nachricht, die empfangen werden soll, wenn die asynchrone Anforderung abgeschlossen ist.

[in] c

Zeiger auf den NULL-Endnamen des Hosts.

[out] d

Zeiger auf den Datenbereich, um die Hostdaten zu empfangen. Der Datenbereich muss größer als die Größe einer Hostentstruktur sein, da der angegebene Datenbereich von Windows Sockets verwendet wird, um eine Hostentstruktur und alle Daten zu enthalten, auf die von Membern der Hostentstruktur verwiesen wird. Ein Puffer von MAXGETHOSTSTRUCT-Bytes wird empfohlen.

[in] e

Größe des Datenbereichs für den buf-Parameter in Bytes.

Rückgabewert

Keine

Bemerkungen

Die WSAAsyncGetHostByName-Funktion ist eine asynchrone Version von gethostbyname und wird verwendet, um Hostnamen- und Adressinformationen abzurufen, die einem Hostnamen entsprechen. Windows Sockets initiiert den Vorgang und kehrt sofort an den Aufrufer zurück, wobei ein undurchsichtiges asynchrones Aufgabenhandle zurückgegeben wird, das die Anwendung zum Identifizieren des Vorgangs verwenden kann. Wenn der Vorgang abgeschlossen ist, werden die Ergebnisse (falls vorhanden) in den vom Aufrufer bereitgestellten Puffer kopiert, und eine Meldung wird an das Anwendungsfenster gesendet.

Wenn der asynchrone Vorgang abgeschlossen ist, empfängt das durch den hWnd-Parameter angegebene Anwendungsfenster eine Meldung im wMsg-Parameter . Der wParam-Parameter enthält das asynchrone Aufgabenhandle, das vom ursprünglichen Funktionsaufruf zurückgegeben wird. Die hohen 16 Bits von lParam enthalten einen beliebigen Fehlercode. Der Fehlercode kann ein beliebiger Fehler sein, wie in Winsock2.h definiert. Der Fehlercode 0 (null) gibt an, dass der asynchrone Vorgang erfolgreich abgeschlossen wurde.

Bei erfolgreicher Fertigstellung enthält der für den ursprünglichen Funktionsaufruf angegebene Puffer eine Hostentstruktur . Um auf die Elemente dieser Struktur zuzugreifen, sollte die ursprüngliche Pufferadresse in einen Hostentstrukturzeiger umgewandelt und nach Bedarf darauf zugegriffen werden.

Wenn der Fehlercode WSAENOBUFS lautet, war die Größe des Puffers, der von buflen im ursprünglichen Aufruf angegeben wurde, zu klein, um alle resultierenden Informationen zu enthalten. In diesem Fall enthalten die niedrigen 16 Bits von lParam die Größe des Puffers, der zum Bereitstellen aller erforderlichen Informationen erforderlich ist. Wenn die Anwendung entscheidet, dass die Teildaten unzureichend sind, kann sie den WSAAsyncGetHostByName-Funktionsaufruf mit einem Puffer erneut ausführen, der groß genug ist, um alle gewünschten Informationen zu empfangen (d. h. nicht kleiner als die niedrigen 16 Bits von lParam).

Der für diese Funktion angegebene Puffer wird von Windows Sockets verwendet, um eine Hostentstruktur zusammen mit dem Inhalt von Datenbereichen zu erstellen, auf die von Membern derselben Hostentstruktur verwiesen wird. Um den WSAENOBUFS-Fehler zu vermeiden, sollte die Anwendung einen Puffer von mindestens MAXGETHOSTSTRUCT-Bytes (wie in Winsock2.h definiert) bereitstellen.

Der Fehlercode und die Pufferlänge sollten aus lParam mithilfe der Makros WSAGETASYNCERROR und WSAGETASYNCBUFLEN extrahiert werden, die in Winsock2.h wie folgt definiert sind:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

Die Verwendung dieser Makros maximiert die Portabilität des Quellcodes für die Anwendung.

WSAAsyncGetHostByName löst garantiert die Zeichenfolge auf, die von einem erfolgreichen Aufruf von gethostname zurückgegeben wird.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wsipv6ok.h (einschließlich Winsock2.h, Winsock.h)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll