WSAAsyncGetHostByAddr, fonction (winsock2.h)
La fonction WSAAsyncGetHostByAddr récupère de façon asynchrone les informations de l’hôte qui correspondent à une adresse.
Syntaxe
HANDLE WSAAPI WSAAsyncGetHostByAddr(
HWND hWnd,
u_int wMsg,
const char *addr,
int len,
int type,
char *buf,
int buflen
);
Paramètres
hWnd
TBD
wMsg
TBD
addr
TBD
len
TBD
type
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, WSAAsyncGetHostByAddr 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 requête. Cette valeur peut être utilisée de deux façons. 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, WSAAsyncGetHostByAddr 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 de l’élément lParam dans le message de réponse à l’aide de la macro WSAGETASYNCERROR .
| Code d'erreur | Signification |
|---|---|
| Le sous-système réseau a échoué. | |
| L’espace de mémoire tampon est insuffisant. | |
| Le paramètre addr ou buf ne se trouve pas dans une partie valide de l’espace d’adressage du processus. | |
| Hôte de réponse faisant autorité introuvable. | |
| Hôte non authentifié introuvable ou SERVERFAIL. | |
| Erreurs non récupérables : FORMERR, REFUSED, NOTIMP. | |
| Nom valide, aucun enregistrement de données de type demandé. |
Les erreurs suivantes peuvent se produire au moment de l’appel de fonction et indiquent 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 Windows Sockets 1.1 bloquant 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 l’instant en raison de contraintes de ressources ou d’autres contraintes au sein de l’implémentation de Windows Sockets. |
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, comme défini 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 pour l’appel de fonction d’origine contient une structure hostente . 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 comme il convient.
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 la mémoire tampon requise pour fournir toutes les informations nécessaires. Si l’application décide que les données partielles sont inadéquates, elle peut réémettre l’appel de fonction WSAAsyncGetHostByAddr avec une mémoire tampon suffisamment grande pour recevoir toutes les informations souhaitées (c’est-à-dire, pas moins de 16 bits 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
| 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 |