Fonction WSAAsyncGetHostByName (winsock2.h)

Article
08/27/2023

La fonction WSAAsyncGetHostByName récupère de manière asynchrone les informations de l’hôte qui correspondent à un nom d’hôte.

Note La fonction WSAAsyncGetHostByName n’est pas conçue pour fournir une résolution parallèle de plusieurs noms. Par conséquent, les applications qui émettent plusieurs requêtes ne doivent pas s’attendre à ce qu’elles soient exécutées simultanément. Les applications peuvent également démarrer un autre thread et utiliser la fonction getaddrinfo pour résoudre les noms de manière indépendante de la version IP. Les développeurs qui créent des applications Windows Sockets 2 sont invités à utiliser la fonction getaddrinfo pour permettre une transition en douceur vers la compatibilité IPv6.

Syntaxe

HANDLE WSAAPI WSAAsyncGetHostByName(
  HWND       hWnd,
  u_int      wMsg,
  const char *name,
  char       *buf,
  int        buflen
);

Paramètres

hWnd

TBD

wMsg

TBD

name

TBD

buf

TBD

buflen

TBD

Valeur retournée

La valeur de retour spécifie si l’opération asynchrone a été lancée avec succès. Cela n’implique pas la réussite ou l’échec de l’opération elle-même.

Si aucune erreur ne se produit, WSAAsyncGetHostByName retourne une valeur différente de zéro de type HANDLE qui est le handle de tâche asynchrone (à ne pas confondre avec un HTASK Windows) pour la demande. Cette valeur peut être utilisée de deux manières. Il peut être utilisé pour annuler l’opération à l’aide de WSACancelAsyncRequest, ou il peut être utilisé pour faire correspondre des opérations asynchrones et des messages d’achèvement en examinant le paramètre de message wParam .

Si l’opération asynchrone n’a pas pu être lancée, WSAAsyncGetHostByName retourne une valeur zéro et un numéro d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Les codes d’erreur suivants peuvent être définis lorsqu’une fenêtre d’application reçoit un message. Comme décrit ci-dessus, ils peuvent être extraits du lParam dans le message de réponse à l’aide de la macro WSAGETASYNCERROR.

Code d'erreur	Signification
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENOBUFS	L’espace tampon est insuffisant.
WSAEFAULT	Le paramètre name ou buf ne se trouve pas dans une partie valide de l’espace d’adressage du processus.
WSAHOST_NOT_FOUND	Hôte de réponse faisant autorité introuvable.
WSATRY_AGAIN	Hôte non authentifié introuvable ou SERVERFAIL.
WSANO_RECOVERY	Erreurs non récupérables : FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Nom valide, aucun enregistrement de données du type demandé.

Les erreurs suivantes peuvent se produire au moment de l’appel de fonction et indiquer que l’opération asynchrone n’a pas pu être lancée.

Code d'erreur	Signification
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEINPROGRESS	Un appel bloquant Windows Sockets 1.1 est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEWOULDBLOCK	L’opération asynchrone ne peut pas être planifiée pour le moment en raison de contraintes de ressources ou d’autres contraintes au sein de l’implémentation des sockets Windows.

Remarques

La fonction WSAAsyncGetHostByName est une version asynchrone de gethostbyname et est utilisée pour récupérer les informations de nom d’hôte et d’adresse correspondant à un nom d’hôte. Windows Sockets lance l’opération et retourne immédiatement à l’appelant, en transmettant un handle de tâche asynchrone opaque que l’application peut utiliser pour identifier l’opération. Une fois l’opération terminée, les résultats (le cas échéant) sont copiés dans la mémoire tampon fournie par l’appelant et un message est envoyé à la fenêtre de l’application.

Une fois l’opération asynchrone terminée, la fenêtre d’application indiquée par le paramètre hWnd reçoit un message dans le paramètre wMsg . Le paramètre wParam contient le handle de tâche asynchrone tel que retourné par l’appel de fonction d’origine. Les 16 bits élevés de lParam contiennent un code d’erreur. Le code d’erreur peut être n’importe quelle erreur définie dans Winsock2.h. Un code d’erreur égal à zéro indique la réussite de l’opération asynchrone.

Une fois l’exécution réussie, la mémoire tampon spécifiée à l’appel de fonction d’origine contient une structure d’hôte . Pour accéder aux éléments de cette structure, l’adresse de mémoire tampon d’origine doit être castée en pointeur de structure hôte et accessible le cas échéant.

Si le code d’erreur est WSAENOBUFS, la taille de la mémoire tampon spécifiée par buflen dans l’appel d’origine était trop petite pour contenir toutes les informations obtenues. Dans ce cas, les 16 bits faibles de lParam contiennent la taille de mémoire tampon requise pour fournir toutes les informations requises. Si l’application décide que les données partielles sont inadéquates, elle peut rééditer l’appel de fonction WSAAsyncGetHostByName avec une mémoire tampon suffisamment grande pour recevoir toutes les informations souhaitées (autrement dit, pas plus petite que les 16 bits faibles de lParam).

La mémoire tampon spécifiée pour cette fonction est utilisée par les sockets Windows pour construire une structure hôte avec le contenu des zones de données référencées par les membres de la même structure hôte . Pour éviter l’erreur WSAENOBUFS , l’application doit fournir une mémoire tampon d’au moins MAXGETHOSTSTRUCT octets (comme défini dans Winsock2.h).

Le code d’erreur et la longueur de la mémoire tampon doivent être extraits de l’objet lParam à l’aide des macros WSAGETASYNCERROR et WSAGETASYNCBUFLEN, définies dans Winsock2.h comme suit :

#include <windows.h>

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

L’utilisation de ces macros optimise la portabilité du code source pour l’application.

WSAAsyncGetHostByName est garanti pour résoudre la chaîne retournée par un appel réussi à gethostname.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winsock2.h (inclure Winsock2.h, Winsock.h)
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll