Fonction de rappel LPWSPSEND (ws2spi.h)
La fonction LPWSPSend envoie des données sur un socket connecté.
Syntaxe
LPWSPSEND Lpwspsend;
int Lpwspsend(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
[in] LPWSATHREADID lpThreadId,
[out] LPINT lpErrno
)
{...}
Paramètres
[in] s
Descripteur identifiant un socket connecté.
[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 LPWSPSend appelée, le système possè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] lpOverlapped
Pointeur vers une structure WSAOverlapped (ignoré pour les sockets non survolés).
[in] lpCompletionRoutine
Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Pointeur vers la routine d’achèvement appelée lorsque l’opération d’envoi est terminée (ignoré pour les sockets non survolé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 d’envoi s’est terminée immédiatement, LPWSPSend 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, une valeur de 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é lancée avec succès 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 de sockets Windows est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
| Le paramètre lpBuffers n’est pas totalement contenu dans une partie valide de l’espace d’adressage utilisateur. | |
| La connexion a été interrompue en raison de la réinitialisation de l’hôte distant. | |
| La connexion a été interrompue, car l'activité persistante a détecté un échec en cours d'opération. | |
| Le socket n'est pas connecté. | |
| 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 de LPWSPSend sur un socket après l’appel de LPWSPShutdown avec la valeur définie sur SD_SEND ou SD_BOTH. | |
| **Windows NT:** Sockets superposés : il y a trop de demandes d’E/S qui se chevauchent. 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 plus grand que le 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’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 LPWSPSend est utilisée pour écrire des données sortantes à partir d’une ou plusieurs mémoires tampons sur un socket orienté connexion spécifié par s. Il peut également être utilisé, toutefois, sur les sockets sans connexion qui ont une adresse d’homologue par défaut spécifiée établie via la fonction LPWSPConnect .
Pour les sockets qui se chevauchent (créés à l’aide de LPWSPSocket avec indicateur WSA_FLAG_OVERLAPPED), cela se produit à l’aide d’E/S qui se chevauchent, 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 nonoverlapped, les paramètres lpOverlapped, lpCompletionRoutine et lpThreadId sont ignorés et LPWSPSend adopte la sémantique synchrone régulière. 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 n’est pas bloquant et orienté flux, et qu’il n’y a pas suffisamment d’espace dans la mémoire tampon du transport, LPWSPSend retourne avec seulement une partie des mémoires tampons fournies ayant été consommées. Compte tenu de la même situation de mémoire tampon et d’un socket bloquant, LPWSPSend bloque jusqu’à ce que tout le contenu de la mémoire tampon fournie ait été consommé.
Le tableau de structures WSABUF pointées vers le paramètre lpBuffers est temporaire. Si cette opération se termine de manière redondante, 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 de message maximale 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 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 LPWSPSend n’indique pas que les données ont été correctement livrées.
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_OOB | Envoie des données OOB (socket de type flux tel que SOCK_STREAM uniquement). |
| MSG_PARTIAL | Spécifie que lpBuffers contient uniquement un message partiel. Notez que le code d’erreur WSAEOPNOTSUPP sera retourné pour les messages qui ne prennent pas en charge les transmissions partielles de messages. |
Si une opération qui se chevauche se termine immédiatement, LPWSPSend 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, LPWSPSend 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. Le client SPI windows Sockets peut 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.
Un fournisseur de services organise l’exécution d’une fonction dans le contexte de thread et de processus appropriés 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.
Un fournisseur de services organise l’exécution d’une fonction dans le thread approprié en appelant WPUQueueApc. Notez que cette fonction doit être appelée dans le contexte du même processus (mais pas nécessairement le même thread) qui a été utilisé pour lancer l’opération qui se chevauche. Il incombe au fournisseur de services de faire en sorte que ce contexte de processus soit actif avant d’appeler WPUQueueApc.
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 |