WSARecvEx, fonction (mswsock.h)

Article
08/25/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 datagramme, le bit MSG_PARTIAL est défini dans le paramètre flags lors du retour de la fonction.

Note La fonction WSARecvEx est une extension propre à Microsoft à la spécification Windows Sockets.

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 entièrement ou partiellement reçu 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 Windows Sockets 1.1 bloquant 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é un échec alors 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êtavec la valeur 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 se bloque.
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 lorsqu’un protocole orienté message est utilisé.

La valeur pointée par le paramètre flags est ignorée lors de l’entrée. Par conséquent, aucun indicateur ne peut ê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 sur l’entrée peut modifier le comportement de la fonction.

Les fonctions WSARecvEx et recv se comportent de façon identique pour les protocoles orientés flux.

Le paramètre flags s’accommode de 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 pointé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 que la fonction recv reçoit toujours un seul message pour chaque appel pour les protocoles de transport orientés message. La fonction recv n’a pas non plus de moyen d’indiquer à l’application que les données reçues ne sont qu’un message partiel. Une application doit générer 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 des protocoles de transport orientés 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 offre 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 façon 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 les applications.

Note Toutes les E/S initiées par un thread donné sont annulées lorsque ce thread se ferme. 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

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