Fonction de rappel LPWSPSENDTO (ws2spi.h)
La fonction LPWSPSendTo envoie des données à une destination spécifique à l’aide d’E/S qui se chevauchent.
Syntaxe
LPWSPSENDTO Lpwspsendto;
int Lpwspsendto(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] const sockaddr *lpTo,
[in] int iTolen,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
[in] LPWSATHREADID lpThreadId,
[out] LPINT lpErrno
)
{...}
Paramètres
[in] s
Descripteur identifiant un socket.
[in] lpBuffers
Pointeur vers un tableau de structures WSABUF . Chaque structure WSABUF contient un pointeur vers une mémoire tampon et la longueur de la mémoire tampon, en octets. Pour une application Winsock, une fois la fonction LPWSPSendTo appelée, le système est propriétaire de ces mémoires tampons et l’application peut ne pas y accéder. Les mémoires tampons de données référencées dans chaque structure WSABUF appartiennent au système et votre application peut ne pas y accéder pendant la durée de vie de l’appel.
[in] dwBufferCount
Nombre de structures WSABUF dans le tableau lpBuffers .
[out] lpNumberOfBytesSent
Pointeur vers le nombre d’octets envoyés par cet appel.
[in] dwFlags
Ensemble d’indicateurs qui spécifie la façon dont l’appel est effectué.
[in] lpTo
Pointeur facultatif vers l’adresse du socket cible dans la structure sockaddr .
[in] iTolen
Taille, en octets, de l’adresse pointée par le paramètre lpTo .
[in] lpOverlapped
Pointeur vers une structure WSAOverlapped (ignoré pour les sockets non inexploités).
[in] lpCompletionRoutine
Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Pointeur vers la routine d’achèvement appelée lorsque l’opération d’envoi a été terminée (ignoré pour les sockets non exécutés).
[in] lpThreadId
Pointeur vers une structure WSATHREADID à utiliser par le fournisseur dans un appel ultérieur à WPUQueueApc. Le fournisseur doit stocker la structure WSATHREADID référencée (pas le pointeur vers le même) jusqu’à ce que la fonction WPUQueueApc soit retournée.
[out] lpErrno
Pointeur vers le code d’erreur.
Valeur retournée
Si aucune erreur ne se produit et que l’opération de réception s’est terminée immédiatement, LPWSPSendTo retourne zéro. Notez que dans ce cas, la routine d’achèvement, si elle est spécifiée, aura déjà été mise en file d’attente. Sinon, la valeur SOCKET_ERROR est retournée et un code d’erreur spécifique est disponible dans lpErrno. Le code d’erreur WSA_IO_PENDING indique que l’opération qui se chevauche a été correctement lancée et que l’achèvement sera indiqué ultérieurement. Tout autre code d’erreur indique qu’aucune opération chevauchée n’a été lancée et qu’aucune indication d’achèvement ne se produira.
| Code d'erreur | Signification |
|---|---|
| Le sous-système réseau a échoué. | |
| L’adresse demandée est une adresse de diffusion, mais l’indicateur approprié n’a pas été défini. | |
| L’appel (bloquant) a été annulé via LPWSPCancelBlockingCall. | |
| Le blocage de l’appel Windows Sockets est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
| Les paramètres lpBuffers ou lpTo ne font pas partie de l’espace d’adressage utilisateur, ou le paramètre lpTo est trop petit. | |
| La connexion a été interrompue, car l'activité persistante a détecté un échec en cours d'opération. | |
| Le fournisseur Windows Sockets signale un interblocage de mémoire tampon. | |
| Le socket n’est pas connecté (sockets orientés connexion uniquement). | |
| Le descripteur n’est pas un socket. | |
| 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, MSG_PARTIAL n’est pas pris en charge, ou le socket est unidirectionnel et prend uniquement en charge les opérations de réception. | |
| Le socket a été arrêté ; il n’est pas possible d’utiliser LPWSPSendTo sur un socket après l’appel de LPWSPShutdownavec la valeur SD_SEND ou SD_BOTH. | |
| Windows NT : 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. | |
| Le socket est orienté message, et le message est supérieur au maximum pris en charge par le transport sous-jacent. | |
| Le socket n’a pas été lié à LPWSPBind, ou le socket n’est pas créé avec l’indicateur superposé. | |
| Le circuit virtuel a été arrêté en raison d’un délai d’attente ou d’une autre défaillance. | |
| Le circuit virtuel a été réinitialisé par le côté distant. | |
| L’adresse distante n’est pas une adresse valide (par exemple, ADDR_ANY). | |
| Impossible d'utiliser les adresses figurant dans la famille spécifiée avec ce socket. | |
| L’adresse de destination est requise. | |
| Le réseau ne peut pas être atteint à partir de cet hôte en ce moment. | |
| 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 LPWSPIoctl. |
Remarques
La fonction LPWSPSendTo est normalement utilisée sur un socket sans connexion spécifié par s pour envoyer un datagramme contenu dans une ou plusieurs mémoires tampons à un socket homologue spécifique identifié par le paramètre lpTo . Même si le socket sans connexion a été précédemment connecté à une adresse spécifique avec la fonction LPWSPConnect , lpTo remplace l’adresse de destination pour ce datagramme particulier uniquement. Sur un socket orienté connexion, les paramètres lpTo et iToLen sont ignorés ; dans ce cas, la fonction LPWSPSendTo est équivalente à LPWSPSend.
Pour les sockets superposés (créés à l’aide de LPWSPSocket avec indicateur WSA_FLAG_OVERLAPPED), cela se produit à l’aide d’E/S superposées, sauf si lpOverlapped et lpCompletionRoutine sont tous deux null , auquel cas le socket est traité comme un socket non superposé. Une indication d’achèvement se produit (appel de la routine d’achèvement ou du paramètre d’un objet d’événement) lorsque la ou les mémoires tampons fournies ont été consommées par le transport. Si l’opération ne se termine pas immédiatement, la status d’achèvement finale est récupérée via la routine d’achèvement ou LPWSPGetOverlappedResult.
Pour les sockets non privilégiés, les paramètres lpOverlapped, lpCompletionRoutine et lpThreadId sont ignorés et LPWSPSendTo adopte la sémantique synchrone normale. Les données sont copiées à partir de la ou des mémoires tampons fournies 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, LPWSPSendTo retourne uniquement une partie des mémoires tampons du client SPI Windows Sockets ayant été consommées. Compte tenu de la même situation de mémoire tampon et d’un socket bloquant, LPWSPSendTo se bloque jusqu’à ce que tout le contenu de la mémoire tampon spi du client Windows Sockets ait été consommé.
Le tableau de structures WSABUF pointées par le paramètre lpBuffers est temporaire. Si cette opération se termine de manière chevauchée, il incombe au fournisseur de services de capturer ces structures WSABUF avant de revenir de cet appel. Cela permet aux applications de créer des tableaux WSABUF basés sur une pile.
Pour les sockets orientés message, vous devez veiller à ne pas dépasser la taille maximale des messages du transport 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 par le protocole sous-jacent, l’erreur WSAEMSGSIZE est retournée et aucune donnée n’est transmise.
Notez que la réussite d’un LPWSPSendTo n’indique pas que les données ont été correctement remises.
Le paramètre iFlags 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_OOB | Envoie des données OOB (socket de type flux comme SOCK_STREAM uniquement). |
| MSG_PARTIAL | Spécifie que 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. |
Si une opération qui se chevauche se termine immédiatement, LPWSPSendTo 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 correctement lancée et se terminera ultérieurement, LPWSPSendTo 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 qui se chevauche se termine, 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é), ou par le biais du paramètre lpcbTransfer dans LPWSPGetOverlappedResult.
Les fournisseurs doivent autoriser l’appel de cette fonction à partir de la routine d’achèvement d’une fonction LPWSPRecv, LPWSPRecvFrom, LPWSPSend ou LPWSPSendTo précédente. Toutefois, pour un socket donné, les routines d’achèvement d’E/S ne peuvent pas être imbriquées. 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 distincte qui se chevauche. La structure WSAOverlapped est définie dans sa propre page de référence.
Si le paramètre lpCompletionRoutine est null, le fournisseur de services signale le membre hEvent de lpOverlapped lorsque l’opération qui se chevauche se termine s’il contient un handle d’objet d’événement valide. Les clients SPI des sockets Windows peuvent utiliser LPWSPGetOverlappedResult pour attendre ou interroger l’objet d’événement.
Si lpCompletionRoutine n’est pas null, le membre hEvent est ignoré et peut être utilisé par le client SPI windows Sockets pour transmettre des informations de contexte à la routine d’achèvement. Un client qui transmet 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 membre hEvent n’est pas définie et une tentative d’attente sur le membre hEvent produirait des résultats imprévisibles.
Il incombe au fournisseur de services d’organiser l’appel de la routine d’achèvement spécifiée par le client une fois l’opération qui se chevauche. Étant donné que la routine d’achèvement doit être exécutée dans le contexte du même thread que celui qui a lancé l’opération chevauchée, elle ne peut pas être appelée directement à partir du fournisseur de services. Le Ws2_32.dll offre un mécanisme d’appel de procédure asynchrone (APC) pour faciliter l’appel des routines d’achèvement.
Un fournisseur de services organise l’exécution d’une fonction dans le thread approprié en appelant WPUQueueApc. Cette fonction peut être appelée à partir de n’importe quel processus et contexte de thread, même un contexte différent du thread et du processus utilisé pour lancer l’opération qui se chevauche.
La fonction WPUQueueApc prend comme paramètres d’entrée un pointeur vers une structure WSATHREADID (fournie au fournisseur via le paramètre d’entrée lpThreadId ), un pointeur vers une fonction APC à appeler et une valeur de contexte qui est ensuite passée à la fonction APC. Étant donné qu’une seule valeur de contexte est disponible, la fonction APC elle-même ne peut pas être la routine d’achèvement spécifiée par le client. Le fournisseur de services doit à la place fournir un pointeur vers sa propre fonction APC, qui utilise la valeur de contexte fournie pour accéder aux informations de résultat nécessaires pour l’opération qui se chevauche, puis appelle la routine d’achèvement spécifiée par le client.
Le prototype de la routine d’achèvement fournie par le client est le suivant.
void CALLBACK
CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine est un espace réservé pour un nom de fonction fourni par le client. dwError spécifie le status d’achèvement pour l’opération qui se chevauche, comme indiqué par lpOverlapped. cbTransferred spécifie le nombre d’octets envoyés. Aucune valeur d’indicateur n’est actuellement définie et la valeur dwFlags sera égale à zéro. Cette fonction ne retourne pas de valeur.
Les routines d’achèvement peuvent être appelées dans n’importe quel ordre, mais pas nécessairement dans le même ordre que celui où les opérations se chevauchent. Toutefois, le fournisseur de services garantit au client que les mémoires tampons publiées sont envoyées dans le même ordre qu’elles sont fournies.
Notes
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 ExitThread .
Spécifications
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| En-tête | ws2spi.h |
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