Fonction WSARecvEx (winsock.h)

Article
08/27/2023

La fonction WSARecvEx reçoit des données d’un socket connecté ou d’un socket sans connexion lié. La fonction WSARecvEx est similaire à la fonction recv , sauf que le paramètre flags est utilisé uniquement pour retourner des informations. Lorsqu’un message partiel est reçu lors de l’utilisation du protocole de datagramme, le bit MSG_PARTIAL est défini dans le paramètre flags au retour de la fonction.

Note La fonction WSARecvEx est une extension spécifique de Microsoft à la spécification des sockets Windows.

Syntaxe

int WSARecvEx(
  [in]      SOCKET s,
  [out]     char   *buf,
  [in]      int    len,
  [in, out] int    *flags
);

Paramètres

[in] s

Descripteur qui identifie un socket connecté.

[out] buf

Pointeur vers la mémoire tampon pour recevoir les données entrantes.

[in] len

Longueur, en octets, de la mémoire tampon pointée vers le paramètre buf .

[in, out] flags

Indicateur spécifiant si le message est reçu entièrement ou partiellement pour les sockets de datagramme.

Valeur retournée

Si aucune erreur ne se produit, WSARecvEx retourne le nombre d’octets reçus. Si la connexion a été fermée, elle retourne zéro. En outre, si un message partiel a été reçu, le bit MSG_PARTIAL est défini dans le paramètre flags . Si un message complet a été reçu, MSG_PARTIAL n’est pas défini dans les indicateurs

Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Important Pour un protocole de transport orienté flux, MSG_PARTIAL n’est jamais défini au retour de WSARecvEx. Cette fonction se comporte de manière identique à la fonction recv pour les protocoles de transport de flux.

Code d'erreur	Signification
WSAECONNABORTED	Le circuit virtuel a été interrompu en raison d'un délai d'attente ou d'un autre échec. L’application doit fermer le socket, car il n’est plus utilisable.
WSAECONNRESET	Le circuit virtuel a été rétabli par la partie distante exécutant une fermeture brutale ou infructueuse. L’application doit fermer le socket, car il n’est plus utilisable. Sur un socket UPD-datagram, cette erreur indique qu'une opération d'envoi précédente a généré un message « Impossible de joindre le port ICMP ».
WSAEFAULT	Le paramètre buf n’est pas entièrement contenu dans une partie valide de l’espace d’adressage utilisateur.
WSAEINPROGRESS	Un appel bloquant Windows Sockets 1.1 est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEINTR	L’appel (bloquant) a été annulé par l’appel WSACancelBlockingCall .
WSAEINVAL	Le socket n’a pas été lié à bind, ou un indicateur inconnu a été spécifié, ou MSG_OOB a été spécifié pour un socket avec SO_OOBINLINE activé ou (pour les sockets de flux d’octets uniquement) len était zéro ou négatif.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENETRESET	Pour un socket orienté connexion, cette erreur indique que la connexion a été interrompue en raison d’une activité de maintien en vie qui a détecté une défaillance pendant que l’opération était en cours. Pour un socket datagramme, cette erreur indique que la durée de vie (TTL, Time to Live) a expiré.
WSAENOTCONN	Le socket n'est pas connecté.
WSAENOTSOCK	Le descripteur n’est pas un socket.
WSAEOPNOTSUPP	MSG_OOB a été spécifié, mais le socket n’est pas de type flux tel que le type SOCK_STREAM, les données OOB ne sont pas prises en charge dans le domaine de communication associé à ce socket, ou le socket est unidirectionnel et prend uniquement en charge les opérations d’envoi.
WSAESHUTDOWN	Le socket a été arrêté ; il n’est pas possible d’utiliser WSARecvEx sur un socket après l’appel de l’arrêt avec la valeur définie sur SD_RECEIVE ou SD_BOTH.
WSAETIMEDOUT	La connexion a été supprimée en raison d'un échec réseau ou d'un échec de réponse du système homologue.
WSAEWOULDBLOCK	Le socket est marqué comme non bloquant et l’opération de réception est bloquée.
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.

Remarques

La fonction WSARecvEx qui fait partie de l’implémentation Microsoft de Windows Sockets 2 est similaire à la fonction recv plus courante, sauf que le paramètre flags est utilisé dans un seul but spécifique. Le paramètre flags est utilisé pour indiquer si un message partiel ou complet est reçu lors de l’utilisation d’un protocole orienté message.

La valeur pointée vers le paramètre flags est ignorée lors de l’entrée. Aucun indicateur ne peut donc être passé à la fonction WSARecvEx pour modifier son comportement. La valeur pointée par le paramètre flags est définie sur la sortie. Cela diffère des fonctions recv et WSARecv où la valeur pointée par le paramètre flags en entrée peut modifier le comportement de la fonction.

Les fonctions WSARecvEx et recv se comportent de la même manière pour les protocoles orientés flux.

Le paramètre flags permet de prendre en charge deux situations courantes dans lesquelles un message partiel est reçu :

Lorsque la taille de la mémoire tampon de données de l’application est inférieure à la taille du message et que le message arrive par hasard en deux parties.
Lorsque le message est assez volumineux et doit arriver en plusieurs morceaux.

Le bit MSG_PARTIAL est défini dans la valeur indiquée par le paramètre flags lors du retour de WSARecvEx lorsqu’un message partiel a été reçu. Si un message complet a été reçu, MSG_PARTIAL n’est pas défini dans la valeur pointée par le paramètre flags .

La fonction recv est différente de la fonction
WSARecvEx et WSARecv fonctionnent en ce sens que la fonction recv reçoit toujours un seul message pour chaque appel pour les protocoles de transport orientés message. La fonction recv ne dispose pas non plus d’un moyen d’indiquer à l’application que les données reçues ne sont qu’un message partiel. Une application doit créer son propre protocole pour vérifier si un message est partiel ou complet en vérifiant le code d’erreur WSAEMSGSIZE après chaque appel à recv. Lorsque la mémoire tampon d’application est plus petite que les données envoyées, la plus grande partie du message est copiée dans la mémoire tampon de l’utilisateur et recv retourne avec le code d’erreur WSAEMSGSIZE. Un appel suivant à recv obtient la partie suivante du message.

Les applications écrites pour les protocoles de transport orienté message doivent être codées pour cette possibilité si le dimensionnement des messages n’est pas garanti par le protocole de transfert de données de l’application. Une application peut utiliser recv et gérer le protocole lui-même. Une application peut également utiliser WSARecvEx et case activée que le bit MSG_PARTIAL est défini dans le paramètre flags.

La fonction WSARecvEx fournit au développeur un moyen plus efficace de vérifier si un message reçu est partiel ou complet lorsqu’un message très volumineux arrive de manière incrémentielle. Par exemple, si une application envoie un message d’un mégaoctet, le protocole de transport doit diviser le message afin de l’envoyer sur le réseau physique. Il est théoriquement possible pour le protocole de transport côté réception de mettre en mémoire tampon toutes les données du message, mais cela serait assez coûteux en termes de ressources. Au lieu de cela, WSARecvEx peut être utilisé, ce qui réduit la surcharge et élimine la nécessité d’un protocole basé sur une application.

Note Toutes les E/S initiées par un thread donné sont annulées à la sortie de ce thread. Pour les sockets qui se chevauchent, les opérations asynchrones en attente peuvent échouer si le thread est fermé avant la fin des opérations. Pour plus d’informations, consultez la fonction ExitThread .

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	winsock.h (inclure Mswsock.h)
Bibliothèque	Mswsock.lib
DLL	Mswsock.dll