WSASendMsg, fonction (winsock2.h)
La fonction WSASendMsg envoie des données et des informations de contrôle facultatives à partir de sockets connectés et non connectés.
Syntaxe
int WSAAPI WSASendMsg(
[in] SOCKET Handle,
[in] LPWSAMSG lpMsg,
[in] DWORD dwFlags,
[out] LPDWORD lpNumberOfBytesSent,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
Paramètres
[in] Handle
Descripteur identifiant le socket.
[in] lpMsg
Structure WSAMSG stockant la structure msghdr Posix.1g.
[in] dwFlags
Indicateurs utilisés pour modifier le comportement de l’appel de fonction WSASendMsg . Pour plus d’informations, consultez Utilisation de dwFlags dans la section Remarques.
[out] lpNumberOfBytesSent
Pointeur vers le nombre, en octets, envoyé par cet appel si l’opération d’E/S se termine immédiatement.
Utilisez NULL pour ce paramètre si le paramètre lpOverlapped n’est pas NULL pour éviter des résultats potentiellement erronés. Ce paramètre peut être NULL uniquement si le paramètre lpOverlapped n’est pas NULL.
[in] lpOverlapped
Pointeur vers une structure WSAOVERLAPPED . Ignoré pour les sockets qui ne se chevauchent pas.
[in] lpCompletionRoutine
Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Pointeur vers la routine d’achèvement appelée lorsque l’opération d’envoi se termine. Ignoré pour les sockets qui ne se chevauchent pas.
Valeur retournée
Retourne zéro en cas de réussite et d’exécution immédiate. Lorsque zéro est retourné, la routine d’achèvement spécifiée est appelée lorsque le thread appelant est dans l’état alertable.
Une valeur de retour de SOCKET_ERROR, puis l’appel suivant à WSAGetLastError qui retourne WSA_IO_PENDING, indiquent que l’opération qui se chevauche a été lancée avec succès . l’achèvement est ensuite indiqué par d’autres moyens, par exemple par le biais d’événements ou de ports d’achèvement.
En cas d’échec, retourne SOCKET_ERROR et un appel ultérieur à WSAGetLastError retourne une valeur autre que WSA_IO_PENDING. Le tableau suivant répertorie les codes d’erreur.
| Code d'erreur | Signification |
|---|---|
| L’adresse demandée est une adresse de diffusion, mais l’indicateur approprié n’a pas été défini. | |
| Pour un socket de datagramme UDP, cette erreur indique qu’une opération d’envoi précédente a entraîné un message ICMP « Port inaccessible ». | |
| Le paramètre lpMsg, lpNumberOfBytesSent, lpOverlapped ou lpCompletionRoutine n’est pas entièrement contenu dans une partie valide de l’espace d’adressage utilisateur. Cette erreur est également retournée si un membre name de la structure WSAMSG pointée par le paramètre lpMsg était un pointeur NULL et que le membre namelen de la structure WSAMSG n’a pas été défini sur zéro. Cette erreur est également retournée si un membre Control.buf de la structure WSAMSG pointée par le paramètre lpMsg était un pointeur NULL et que le membre Control.len de la structure WSAMSG n’a pas été défini sur zéro. | |
| Un appel Windows Sockets 1.1 bloquant est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
| Un appel Windows Socket 1.1 bloquant a été annulé via WSACancelBlockingCall. | |
| Le socket n’a pas été lié à une liaison, ou le socket n’a pas été créé avec l’indicateur superposé. | |
| Le socket est orienté message, et le message est supérieur à la valeur maximale prise en charge par le transport sous-jacent. | |
| Le sous-système réseau a échoué. | |
| Pour un socket datagramme, cette erreur indique que la durée de vie (TTL, Time to Live) a expiré. | |
| Le réseau est inaccessible. | |
| Le fournisseur Windows Sockets signale un interblocage de mémoire tampon. | |
| Le socket n'est pas connecté. | |
| Le descripteur n’est pas un socket. | |
| L’opération de socket n’est pas prise en charge. Cette erreur est retournée si le membre dwFlags de la structure WSAMSG pointée vers par le paramètre lpMsg inclut des indicateurs de contrôle non valides pour WSASendMsg. | |
| Le socket a été arrêté ; il n’est pas possible d’appeler la fonction WSASendMsg sur un socket après l’appel de l’arrêtavec la valeur SD_SEND ou SD_BOTH. | |
| Le socket a expiré. Cette erreur est retournée si le socket avait un délai d’attente spécifié à l’aide de l’option de socket SO_SNDTIMEO et si le délai d’attente a été dépassé. | |
| Sockets qui se chevauchent : il y a trop de demandes d’E/S qui se chevauchent en attente. Sockets non bloqués : le socket est marqué comme non bloquant et l’opération d’envoi ne peut pas être effectuée immédiatement. | |
| Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction. | |
| Une opération superposée a été lancée avec succès et l’achèvement sera indiqué ultérieurement. | |
| L’opération qui se chevauche a été annulée en raison de la fermeture du socket ou de l’exécution de la commande SIO_FLUSH dans WSAIoctl. |
Remarques
La fonction WSASendMsg peut être utilisée à la place des fonctions WSASend et WSASendTo . La fonction WSASendMsg ne peut être utilisée qu’avec des datagrammes et des sockets bruts. Le descripteur de socket dans le paramètre s doit être ouvert avec le type de socket défini sur SOCK_DGRAM ou SOCK_RAW.
Le paramètre dwFlags ne peut contenir qu’une combinaison des indicateurs de contrôle suivants : MSG_DONTROUTE, MSG_PARTIAL et MSG_OOB. Le membre dwFlags de la structure WSAMSG pointée vers le paramètre lpMsg est ignoré en entrée et non utilisé en sortie.
Les sockets qui se chevauchent sont créés avec un appel de fonction WSASocket dont l’indicateur WSA_FLAG_OVERLAPPED est défini. Pour les sockets qui se chevauchent, l’envoi d’informations utilise des E/S qui se chevauchent, sauf si lpOverlapped et lpCompletionRoutine ont la valeur NULL ; lorsque lpOverlapped et lpCompletionRoutine ont la valeur NULL, le socket est traité comme un socket non inexploité. Une indication d’achèvement se produit avec des sockets qui se chevauchent ; une fois que la mémoire tampon ou les mémoires tampons ont été consommées par le transport, une routine d’achèvement est déclenchée ou un objet d’événement est défini. Si l’opération ne se termine pas immédiatement, l’achèvement final status est récupéré via la routine d’achèvement ou en appelant la fonction WSAGetOverlappedResult.
Pour les sockets non intégrés, les paramètres lpOverlapped et lpCompletionRoutine sont ignorés et WSASendMsg adopte la même sémantique de blocage que la fonction d’envoi : les données sont copiées à partir de la mémoire tampon ou des mémoires tampons dans la mémoire tampon du transport. Si le socket est non bloquant et orienté flux, et qu’il n’y a pas suffisamment d’espace dans la mémoire tampon du transport, WSASendMsg retourne avec seulement une partie des mémoires tampons de l’application ayant été consommées. En revanche, cette situation de mémoire tampon sur un socket bloquant entraîne le blocage de WSASendMsg jusqu’à ce que tout le contenu de la mémoire tampon de l’application ait été consommé.
Si cette fonction se chevauche, il incombe au fournisseur de services Winsock de capturer cette structure WSABUF avant de revenir de cet appel. Cela permet aux applications de créer des tableaux WSABUF basés sur une pile pointés par le membre lpBuffers de la structure WSAMSG vers laquelle pointe le paramètre lpMsg .
Pour les sockets orientés message, vous devez veiller à ne pas dépasser la taille maximale des messages du fournisseur sous-jacent, qui peut être obtenue en obtenant la valeur de l’option de socket SO_MAX_MSG_SIZE. Si les données sont trop longues pour être transmises atomiquement via le protocole sous-jacent, l’erreur WSAEMSGSIZE est retournée et aucune donnée n’est transmise.
Sur un socket IPv4 de type SOCK_DGRAM ou SOCK_RAW, une application peut préciser l’adresse IP source locale à utiliser pour l’envoi avec la fonction WSASendMsg . L’un des objets de données de contrôle passés dans la structure WSAMSG à la fonction WSASendMsg peut contenir une structure in_pktinfo utilisée pour spécifier l’adresse source IPv4 locale à utiliser pour l’envoi.
Sur un socket IPv6 de type SOCK_DGRAM ou SOCK_RAW, une application peut spécifique l’adresse IP source locale à utiliser pour l’envoi avec la fonction WSASendMsg . L’un des objets de données de contrôle transmis dans la structure WSAMSG à la fonction WSASendMsg peut contenir une structure in6_pktinfo utilisée pour spécifier l’adresse source IPv6 locale à utiliser pour l’envoi.
Pour un socket à double pile lors de l’envoi de datagrammes avec la fonction WSASendMsg et qu’une application souhaite spécifier une adresse IP source locale spécifique à utiliser, la méthode pour gérer cela dépend de l’adresse IP de destination. Lors de l’envoi à une adresse de destination IPv4 ou à une adresse de destination IPv6 mappée IPv4, l’un des objets de données de contrôle transmis dans la structure WSAMSG pointée par le paramètre lpMsg doit contenir une structure in_pktinfo contenant l’adresse source IPv4 locale à utiliser pour l’envoi. Lors de l’envoi à une adresse de destination IPv6 qui n’est pas une adresse IPv6 mappée par IPv4, l’un des objets de données de contrôle transmis dans la structure WSAMSG pointée par le paramètre lpMsg doit contenir une structure in6_pktinfo contenant l’adresse source IPv6 locale à utiliser pour l’envoi.
dwFlags
Le paramètre d’entrée dwFlags peut être utilisé pour influencer le comportement de l’appel de fonction au-delà des options spécifiées pour le socket associé. Autrement dit, la sémantique de cette fonction est déterminée par les options de socket et le paramètre dwFlags . Ce dernier est construit à l’aide de l’opérateur OR au niveau du bit avec l’une des valeurs suivantes.| Valeur | Signification |
|---|---|
| MSG_DONTROUTE | Spécifie que les données ne doivent pas faire l’objet d’un routage. Un fournisseur de services Windows Sockets peut choisir d’ignorer cet indicateur. |
| MSG_PARTIAL | Spécifie que lpMsg-lpBuffers> contient uniquement un message partiel. Notez que le code d’erreur WSAEOPNOTSUPP sera retourné par les transports qui ne prennent pas en charge les transmissions partielles de messages. |
Lors de la sortie, le membre dwFlags de la structure WSAMSG pointée vers le paramètre lpMsg n’est pas utilisé.
E/S de sockets qui se chevauchent
Si une opération qui se chevauche se termine immédiatement, WSASendMsg retourne une valeur de zéro et le paramètre lpNumberOfBytesSent est mis à jour avec le nombre d’octets envoyés. Si l’opération qui se chevauche est correctement lancée et se terminera ultérieurement, WSASendMsg retourne SOCKET_ERROR et indique le code d’erreur WSA_IO_PENDING. Dans ce cas, lpNumberOfBytesSent n’est pas mis à jour. Une fois l’opération qui se chevauche, la quantité de données transférées est indiquée par le biais du paramètre cbTransferred dans la routine d’achèvement (si spécifiée) ou par le biais du paramètre lpcbTransfer dans WSAGetOverlappedResult.La fonction WSASendMsg à l’aide d’E/S qui se chevauchent peut être appelée à partir de la routine d’achèvement d’une fonction précédente , WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg),WSASend, WSASendMsg ou WSASendTo. Cela permet aux transmissions de données sensibles au temps de se produire entièrement dans un contexte préemptif.
Le paramètre lpOverlapped doit être valide pendant la durée de l’opération qui se chevauche. Si plusieurs opérations d’E/S sont simultanément en attente, chacune doit référencer une structure WSAOVERLAPPED distincte.
Si le paramètre lpCompletionRoutine a la valeur NULL, le paramètre hEvent de lpOverlapped est signalé lorsque l’opération qui se chevauche se termine s’il contient un handle d’objet d’événement valide. Une application peut utiliser WSAWaitForMultipleEvents ou WSAGetOverlappedResult pour attendre ou interroger l’objet d’événement.
Si lpCompletionRoutine n’a pas la valeur NULL, le paramètre hEvent est ignoré et peut être utilisé par l’application pour transmettre des informations de contexte à la routine d’achèvement. Un appelant qui passe un lpCompletionRoutine non NULL et appelle ultérieurement WSAGetOverlappedResult pour la même demande d’E/S qui se chevauche peut ne pas définir le paramètre fWait pour cet appel de WSAGetOverlappedResult sur TRUE. Dans ce cas, l’utilisation du paramètre hEvent n’est pas définie et une tentative d’attente sur le paramètre hEvent produirait des résultats imprévisibles.
La routine d’achèvement suit les mêmes règles que celles spécifiées pour les routines d’achèvement d’E/S de fichiers Windows. La routine d’achèvement n’est pas appelée tant que le thread n’est pas dans un état d’attente pouvant être alerté, par exemple, avec WSAWaitForMultipleEvents appelé avec le paramètre fAlertable défini sur TRUE.
Les fournisseurs de transport permettent à une application d’appeler des opérations d’envoi et de réception à partir du contexte de la routine d’achèvement des E/S du socket et garantissent que, pour un socket donné, les routines d’achèvement des E/S ne seront pas imbriquées. Cela permet aux transmissions de données sensibles au temps de se produire entièrement dans un contexte préemptif.
Le prototype de la routine d’achèvement est le suivant.
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
La fonction CompletionRoutine est un espace réservé pour un nom de fonction défini par l’application ou défini par la bibliothèque. Le paramètre dwError spécifie la status d’achèvement pour l’opération qui se chevauche, comme indiqué par le paramètre lpOverlapped. Le paramètre cbTransferred indique le nombre d’octets envoyés. Actuellement, aucune valeur d’indicateur n’est définie et le paramètre dwFlags sera égal à zéro. La fonction CompletionRoutine ne retourne pas de valeur.
Le retour à partir de cette fonction permet l’appel d’une autre routine d’achèvement en attente pour le socket. Toutes les routines d’achèvement en attente sont appelées avant que l’attente du thread pouvant être alerté soit satisfaite avec un code de retour de WSA_IO_COMPLETION. Les routines d’achèvement peuvent être appelées dans n’importe quel ordre, pas nécessairement dans le même ordre que les opérations qui se chevauchent. Toutefois, il est garanti que les mémoires tampons publiées soient envoyées dans l’ordre spécifié.
Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 8.1, Windows Vista [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | winsock2.h (inclure Mswsock.h) |
| Bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour