WSARecvEx, fonction (mswsock.h)

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

Voir aussi

WSAAsyncSelect

WSARecv

Winsock Functions

Référence Winsock

Recv

recvfrom

select

envoyer

socket