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.

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.

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.

Spécifications

Voir aussi

WPUQueueApc

LPWSPGetOverlappedResult

LPWSPSocket