WSASendMsg, fonction (winsock2.h)

Article
07/16/2024

La fonction WSASendMsg envoie des données et des informations de contrôle facultatives à partir de sockets connectés et non connectés.

Remarque Cette fonction est une extension spécifique à Microsoft à la spécification windows Sockets.

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 les résultats potentiellement erronés. Ce paramètre peut être null uniquement si le paramètre 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 de retour

Retourne zéro lorsque la réussite et l’achèvement immédiat se produisent. 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 à WSAGetLastError qui retourne WSA_IO_PENDING, indique que l’opération qui se chevauche a été lancée ; la saisie semi-automatique est ensuite indiquée par d’autres moyens, comme 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
WSAEACCES	L’adresse demandée est une adresse de diffusion, mais l’indicateur approprié n’a pas été défini.
WSAECONNRESET	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 ».
WSAEFAULT	Le lpMsg, lpNumberOfBytesSent, lpOverlapped, ou paramètre lpCompletionRoutine n’est pas totalement contenu dans une partie valide de l’espace d’adressage utilisateur. Cette erreur est également retournée si un nom membre de la structure WSAMSG pointée par le paramètre lpMsg était un pointeur NULL et 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 le membre Control.len de la structure WSAMSG n’a pas été défini sur zéro.
WSAEINPROGRESS	Un appel Windows Sockets 1.1 bloquant est en cours, ou le fournisseur de services traite toujours une fonction de rappel.
WSAEINTR	Un appel Windows Socket 1.1 bloquant a été annulé via WSACancelBlockingCall.
WSAEINVAL	Le socket n’a pas été lié à liaison, ou le socket n’a pas été créé avec l’indicateur superposé.
WSAEMSGSIZE	Le socket est orienté message et le message est supérieur au maximum pris en charge par le transport sous-jacent.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENETRESET	Pour un socket de datagramme, cette erreur indique que la durée de vie a expiré.
WSAENETUNREACH	Le réseau est inaccessible.
WSAENOBUFS	Le fournisseur Windows Sockets signale un blocage de mémoire tampon.
WSAENOTCONN	Le socket n’est pas connecté.
WSAENOTSOCK	Le descripteur n’est pas un socket.
WSAEOPNOTSUPP	L’opération de socket n’est pas prise en charge. Cette erreur est retournée si le dwFlags membre de la structure WSAMSG pointée par le paramètre lpMsg inclut les indicateurs de contrôle non valides pour WSASendMsg.
WSAESHUTDOWN	Le socket a été arrêté ; Il n’est pas possible d’appeler la fonction WSASendMsg sur un socket après 'arrêt a été appelée avec comment défini sur SD_SEND ou SD_BOTH.
WSAETIMEDOUT	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 que le délai d’attente a été dépassé.
WSAEWOULDBLOCK	Sockets superposés : il y a trop de demandes d’E/S superposées 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.
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSA_IO_PENDING	Une opération superposée a été lancée et l’achèvement sera indiqué ultérieurement.
WSA_OPERATION_ABORTED	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 de 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_PARTIALet MSG_OOB. Le dwFlags membre de la structure WSAMSG pointée par le paramètre lpMsg est ignorée lors de l’entrée et n’est pas utilisée sur la sortie.

Remarque Le pointeur de fonction pour la fonction WSASendMsg doit être obtenu au moment de l’exécution en effectuant un appel à la fonction WSAIoctl avec le SIO_GET_EXTENSION_FUNCTION_POINTER opcode spécifié. La mémoire tampon d’entrée transmise à la fonction WSAIoctl doit contenir WSAID_WSASENDMSG, un identificateur global unique (GUID) dont la valeur identifie la fonction d’extension WSASendMsg. En cas de réussite, la sortie retournée par la fonction WSAIoctl contient un pointeur vers la fonction WSASendMsg. Le GUID WSAID_WSASENDMSG est défini dans le fichier d’en-tête Mswsock.h.

Les sockets superposés sont créés avec un appel de fonction WSASocket dont l’indicateur de WSA_FLAG_OVERLAPPED est défini. Pour les sockets superposés, l’envoi d’informations utilise des E/S superposées, sauf si les deux lpOverlapped et lpCompletionRoutine sont null; lorsque lpOverlapped et lpCompletionRoutine sont NULL, le socket est traité comme un socket non-incapitulé. Une indication d’achèvement se produit avec des sockets superposés ; 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’état d’achèvement final est récupéré via la routine d’achèvement ou en appelant la fonction WSAGetOverlappedResult.

Pour les sockets non privilégiés, les paramètres lpOverlapped et lpCompletionRoutine sont ignorés et WSASendMsg adopte la même sémantique bloquante que la fonction envoyer : 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 n’est pas bloquant et orienté flux, et qu’il y a un espace insuffisant dans la mémoire tampon du transport, WSASendMsg retourne uniquement 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 WSASendMsg bloquant jusqu’à ce que tout le contenu de la mémoire tampon de l’application ait été consommé.

Si cette fonction est terminée de manière superposée, il incombe au fournisseur de services Winsock de capturer cette structure WSABUF avant de retourner à partir de cet appel. Cela permet aux applications de créer des tableaux WSABUF basés sur la pile membres de la structure WSAMSG pointée par le paramètre lpMsg .

Pour les sockets orientés messages, vous devez veiller à ne pas dépasser la taille maximale du message 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 passer 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 spécifique à l’adresse source IP 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 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 source IP 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 source IP locale spécifique à utiliser, la méthode à gérer dépend de l’adresse IP de destination. Lors de l’envoi à une adresse de destination IPv4 ou à une adresse de destination IPv4 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 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.

Remarque l’option de socket SO_SNDTIMEO s’applique uniquement aux sockets bloquants.

Remarque La réussite d’un WSASendMsg n’indique pas que les données ont été correctement remises.

Remarque Lors de l’émission d’un appel Winsock bloquant tel que WSASendMsg avec le paramètre lpOverlapped défini sur NULL, Winsock peut avoir besoin d’attendre un événement réseau avant la fin de l’appel. Winsock effectue une attente alertable dans cette situation, qui peut être interrompue par un appel de procédure asynchrone (APC) planifié sur le même thread. L’émission d’un autre appel Winsock bloquant à l’intérieur d’un APC qui a interrompu un appel Winsock bloquant en cours sur le même thread entraîne un comportement non défini et ne doit jamais être tenté par les clients Winsock.

dwFlags

Les dwFlags paramètre d’entrée peuvent être utilisés 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 être soumises au 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.

Les valeurs possibles pour paramètre dwFlags sont définies dans le fichier d’en-tête Winsock2.h.

Lors de la sortie, la structure dwFlags de la structure WSAMSG pointée par le paramètre lpMsg n’est pas utilisée.

E/S de socket superposé

Si une opération se chevauche immédiatement, WSASendMsg retourne la valeur 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 lancée et se termine ultérieurement, WSASendMsg retourne SOCKET_ERROR et indique le code d’erreur WSA_IO_PENDING. Dans ce cas, lpNumberOfBytesSent n’est pas mis à jour. Lorsque l’opération se chevauche, la quantité de données transférées est indiquée via le paramètre cbTransferred dans la routine d’achèvement (le cas échéant) ou via le paramètre lpcbTransfer dans WSAGetOverlappedResult.

Remarque toutes les E/S lancées par un thread donné sont annulées lorsque ce thread se termine. Pour les sockets superposés, les opérations asynchrones en attente peuvent échouer si le thread est fermé avant la fin des opérations. Pour plus d’informations, consultez exitThread.

La fonction WSASendMsg à l’aide d’E/S superposées peut être appelée à partir de la routine d’achèvement d’un WSARecv précédent , WSARecvFrom, LPFN_WSARECVMSG(WSARecvMsg), WSASend, WSASendMsgou fonction 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 faire référence à une structure WSAOVERLAPPED distincte.

Si le paramètre lpCompletionRoutine est NULL, le paramètre hEvent de lpOverlapped est signalé lorsque l’opération qui se chevauche se termine si elle contient un handle d’objet d’événement valide. Une application peut utiliser WSAWaitForMultipleEvents ou WSAGetOverlappedResult attendre ou interroger l’objet d’événement.

Si lpCompletionRoutine n’est pas 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 unNULLlpCompletionRoutine et versions ultérieures appelle WSAGetOverlappedResult pour la même requête d’E/S superposée ne peut 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 la tentative d’attente sur le paramètre hEvent produit des résultats imprévisibles.

La routine d’achèvement suit les mêmes règles que celles stipulées pour les routines d’achèvement des E/S de fichier Windows. La routine d’achèvement ne sera pas appelée tant que le thread n’est pas dans un état d’attente alertable, par exemple, avec WSAWaitForMultipleEvents appelée 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 d’E/S de socket et de garantir que, pour un socket donné, les routines d’achèvement d’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 une bibliothèque. Le paramètre dwError spécifie l’état d’achèvement de 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, il n’existe aucune valeur d’indicateur définie et le paramètre dwFlags sera égal à zéro. La fonction CompletionRoutine ne retourne pas de valeur.

Le retour 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 alertable soit satisfaite d’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 superposées sont terminées. Toutefois, les mémoires tampons publiées sont garanties d’être envoyées dans le même ordre qu’elles sont spécifiées.

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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	winsock2.h (inclure Mswsock.h)
bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll