WSAAsyncGetHostByAddr, macro (wsipv6ok.h)

Article
08/28/2023

La fonction WSAAsyncGetHostByAddr récupère de manière asynchrone les informations de l’hôte qui correspondent à une adresse.

Note La fonction WSAAsyncGetHostByAddr n’est pas conçue pour fournir une résolution parallèle de plusieurs adresses. 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 getnameinfo pour résoudre les adresses 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 getnameinfo pour permettre une transition fluide vers la compatibilité IPv6.

Syntaxe

void WSAAsyncGetHostByAddr(
  [in]   a,
  [in]   b,
  [in]   c,
  [in]   d,
  [in]   e,
  [out]  f,
  [in]   g
);

Paramètres

[in] a

Gérer la fenêtre qui recevra un message à la fin de la demande asynchrone.

[in] b

Message à recevoir à la fin de la demande asynchrone.

[in] c

Pointeur vers l’adresse réseau de l’hôte. Les adresses hôtes sont stockées dans l’ordre des octets réseau.

[in] d

Longueur de l’adresse, en octets.

[in] e

Type de l’adresse.

[out] f

Pointeur vers la zone de données pour recevoir les données de l’hôte . La zone de données doit être supérieure à la taille d’une structure d’hôte , car la zone de données est utilisée par les sockets Windows pour contenir une structure d’hôte et toutes les données référencées par les membres de la structure hôte . Une mémoire tampon d’octets MAXGETHOSTSTRUCT est recommandée.

[in] g

Taille de la zone de données pour le paramètre buf , en octets.

Valeur de retour

None

Remarques

La fonction WSAAsyncGetHostByAddr est une version asynchrone de gethostbyaddr. Il est utilisé pour récupérer le nom d’hôte et les informations d’adresse qui correspondent à une adresse réseau. Windows Sockets lance l’opération et retourne immédiatement à l’appelant, en transmettant un handle de tâche opaque et asynchrone 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 membres de cette structure, l’adresse de mémoire tampon d’origine est convertie 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 WSAAAsyncGetHostByAddr avec une mémoire tampon suffisamment grande pour recevoir toutes les informations souhaitées (c’est-à-dire, 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 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.

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	wsipv6ok.h (inclure Winsock2.h, Winsock.h)
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll