Fonction WSAAsyncGetProtoByName (winsock2.h)

La fonction WSAAsyncGetProtoByName récupère de manière asynchrone les informations de protocole qui correspondent à un nom de protocole.

Syntaxe

HANDLE WSAAPI WSAAsyncGetProtoByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [out] char       *buf,
  [out] int        buflen
);

Paramètres

[in] hWnd

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

[in] wMsg

Message à recevoir à la fin de la demande asynchrone.

[in] name

Pointeur vers le nom de protocole terminé par null à résoudre.

[out] buf

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

[out] buflen

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

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, WSAAsyncGetProtoByName retourne une valeur différente de zéro de type HANDLE qui est le handle de tâche asynchrone pour la requête (à ne pas confondre avec un HTASK Windows). 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 les opérations asynchrones et les messages d’achèvement, en examinant le paramètre de message wParam .

Si l’opération asynchrone n’a pas pu être lancée, WSAAsyncGetProtoByName 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 .

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.

Remarques

La fonction WSAAsyncGetProtoByName est une version asynchrone de getprotobyname. Il est utilisé pour récupérer le nom et le numéro du protocole à partir de la base de données Sockets Windows correspondant à un nom de protocole donné. 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 protoente . Pour accéder aux membres de cette structure, l’adresse de mémoire tampon d’origine doit être convertie en pointeur de structure protoente et accessible selon les besoins.

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 WSAAAsyncGetProtoByName 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 protoente avec le contenu des zones de données référencées par les membres de la même structure protoente . Pour éviter l’erreur WSAENOBUFS mentionnée ci-dessus, 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

Voir aussi

WSACancelAsyncRequest

Fonctions Winsock

Informations de référence sur Winsock

getprotobyname