WSAAsyncGetHostByName-Funktion (winsock.h)
Die WSAAsyncGetHostByName-Funktion ruft asynchron Hostinformationen ab, die einem Hostnamen entsprechen.
Syntax
HANDLE WSAAsyncGetHostByName(
HWND hWnd,
u_int wMsg,
const char *name,
char *buf,
int buflen
);
Parameter
hWnd
TBD
wMsg
TBD
name
TBD
buf
TBD
buflen
TBD
Rückgabewert
Der Rückgabewert gibt an, ob der asynchrone Vorgang erfolgreich initiiert wurde. Dies impliziert keinen Erfolg oder Misserfolg des Vorgangs selbst.
Wenn kein Fehler auftritt, gibt WSAAsyncGetHostByName einen nonzero-Wert vom Typ HANDLE zurück, der das asynchrone Aufgabenhandle (nicht mit einem Windows HTASK zu verwechseln) für die Anforderung ist. Dieser Wert kann auf zwei Arten verwendet werden. Es kann verwendet werden, um den Vorgang mit WSACancelAsyncRequest abzubrechen, oder es kann verwendet werden, um asynchrone Vorgänge und Vervollständigungsmeldungen abzugleichen, indem der wParam-Nachrichtenparameter untersucht wird.
Wenn der asynchrone Vorgang nicht initiiert werden konnte, gibt WSAAsyncGetHostByName einen Nullwert zurück, und eine bestimmte Fehlernummer kann durch Aufrufen von WSAGetLastError abgerufen werden.
Die folgenden Fehlercodes können festgelegt werden, wenn ein Anwendungsfenster eine Nachricht empfängt. Wie oben beschrieben, können sie aus dem lParam in der Antwortnachricht mithilfe des WSAGETASYNCERROR-Makros extrahiert werden.
Fehlercode | Bedeutung |
---|---|
Beim Netzwerksubsystem ist ein Fehler aufgetreten. | |
Es ist nicht genügend Pufferspeicher verfügbar. | |
Der Name oder buf-Parameter befindet sich nicht in einem gültigen Teil des Prozessadressraums. | |
Autorisierender Antworthost nicht gefunden. | |
Ein nicht autoritativer Host nicht gefunden oder SERVERFAIL. | |
Nicht behebbare Fehler: FORMERR, REFUSED, NOTIMP. | |
Gültiger Name, kein Datensatz des angeforderten Typs. |
Die folgenden Fehler können zum Zeitpunkt des Funktionsaufrufs auftreten und zeigen an, dass der asynchrone Vorgang nicht initiiert werden konnte.
Fehlercode | Bedeutung |
---|---|
WSANOTINITIALISED | Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen. |
WSAENETDOWN | Beim Netzwerksubsystem ist ein Fehler aufgetreten. |
WSAEINPROGRESS | Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion. |
WSAEWOULDBLOCK | Der asynchrone Vorgang kann derzeit aufgrund von Ressourcen oder anderen Einschränkungen innerhalb der Windows Sockets-Implementierung nicht geplant werden. |
Hinweise
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 Nachricht wird an das Fenster der Anwendung gesendet.
Wenn der asynchrone Vorgang abgeschlossen ist, empfängt das durch den hWnd-Parameter angegebene Anwendungsfenster eine Nachricht 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, der in Winsock2.h definiert ist. Ein Fehlercode von null zeigt den erfolgreichen Abschluss des asynchronen Vorgangs an.
Nach 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 hostenten Strukturzeiger umgewandelt und nach Bedarf darauf zugegriffen werden.
Wenn der Fehlercode WSAENOBUFS ist, 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 ausgeben, der groß genug ist, um alle gewünschten Informationen zu empfangen (d. a. 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 Mitgliedern derselben Hostentstruktur verwiesen wird. Um den WSAENOBUFS-Fehler zu vermeiden, sollte die Anwendung einen Puffer von mindestens MAXGETHOSTSTRUCT-Bytes bereitstellen (wie in Winsock2.h definiert).
Der Fehlercode und die Pufferlänge sollten mithilfe der Makros WSAGETASYNCERROR und WSAGETASYNCBUFLEN aus dem lParam extrahiert werden, die in Winsock2.h als 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 durch einen 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 | winsock.h (einschließlich Winsock2.h, Winsock.h) |
Bibliothek | Ws2_32.lib |
DLL | Ws2_32.dll |