Fonction de rappel LPWSPGETOVERLAPPEDRESULT (ws2spi.h)

Article
03/04/2024

La fonction LPWSPGetOverlappedResult retourne les résultats d’une opération qui se chevauche sur le socket spécifié.

Syntaxe

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

Paramètres

[in] s

Identifie le socket. Il s’agit du même socket qui a été spécifié lorsque l’opération qui se chevauche a été démarrée par un appel à LPWSPRecv, LPWSPRecvFrom, LPWSPSend, LPWSPSendTo ou LPWSPIoctl.

[in] lpOverlapped

Pointeur vers une structure WSAOverlapped qui a été spécifiée lors du démarrage de l’opération qui se chevauche.

[out] lpcbTransfer

Pointeur vers une variable 32 bits qui reçoit le nombre d’octets réellement transférés par une opération d’envoi ou de réception, ou par LPWSPIoctl.

[in] fWait

Spécifie si la fonction doit attendre la fin de l’opération en attente qui se chevauche. Si la valeur est TRUE, la fonction ne retourne pas tant que l’opération n’est pas terminée. Si FALSE et l’opération est toujours en attente, la fonction retourne FALSE et lpErrno est WSA_IO_INCOMPLETE. Le paramètre fWait peut être défini sur TRUE uniquement si l’opération qui se chevauche a sélectionné une notification d’achèvement basée sur les événements.

[out] lpdwFlags

Pointeur vers une variable 32 bits qui recevra un ou plusieurs indicateurs qui complètent la status d’achèvement. Si l’opération qui se chevauche a été lancée via LPWSPRecv ou LPWSPRecvFrom, ce paramètre contient la valeur des résultats pour le paramètre lpFlags .

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si LPWSPGetOverlappedResult réussit, la valeur de retour est TRUE. Cela signifie que l’opération qui se chevauche s’est terminée avec succès et que la valeur pointée par lpcbTransfer a été mise à jour. Si LPWSPGetOverlappedResult retourne FALSE, cela signifie que l’opération qui se chevauche n’est pas terminée ou que l’opération se chevauche, mais avec des erreurs, ou que l’achèvement status n’a pas pu être déterminé en raison d’erreurs dans un ou plusieurs paramètres dans LPWSPGetOverlappedResult. En cas d’échec, la valeur pointée par lpcbTransfer n’est pas mise à jour. Le paramètre lpErrno indique la cause de la défaillance (soit de LPWSPGetOverlappedResult , soit de l’opération superposée associée).

Code d'erreur	Signification
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENOTSOCK	Le descripteur n’est pas un socket.
WSA_INVALID_HANDLE	Le membre hEvent de la structure WSAOverlapped ne contient pas de handle d’objet d’événement valide.
WSAEINVAL	L’un des paramètres est inacceptable.
WSA_IO_INCOMPLETE	Le paramètre fWait est FALSE et l’opération d’E/S n’est pas encore terminée.

Remarques

Les résultats signalés par la fonction LPWSPGetOverlappedResult sont ceux de la dernière opération de chevauchement du socket spécifié à laquelle la structure WSAOverlapped spécifiée a été fournie et pour laquelle les résultats de l’opération étaient en attente. Une opération en attente est indiquée lorsque la fonction qui a démarré l’opération retourne SOCKET_ERROR et que le lpErrno est WSA_IO_PENDING. Lorsqu’une opération d’E/S est en attente, la fonction qui a démarré l’opération réinitialise le membre hEvent de la structure WSAOVERLAPPED à l’état non signé. Ensuite, une fois l’opération en attente terminée, le système définit l’objet événement à l’état signalé.

Si le paramètre fWait a la valeur TRUE, LPWSPGetOverlappedResult détermine si l’opération en attente a été terminée en bloquant et en attendant que l’objet d’événement soit à l’état signalé. Un client peut définir le paramètre fWait sur TRUE uniquement s’il a sélectionné une notification d’achèvement basée sur les événements lorsque l’opération d’E/S a été demandée. Si une autre forme de notification a été sélectionnée, l’utilisation du membre hEvent de la structure WSAOverlapped est différente et la définition de fWait sur TRUE entraîne des résultats imprévisibles.

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 .

Interaction avec WPUCompleteOverlappedRequest

Le comportement de WPUCompleteOverlappedRequest impose certaines contraintes sur la façon dont un fournisseur de services implémente LPWSPGetOverlappedResult , car seuls les membres Offset et OffsetHigh de la structure WSAOverlapped sont exclusivement contrôlés par le fournisseur de services même si trois valeurs (nombre d’octets, indicateurs et erreur) doivent être récupérées à partir de la structure par LPWSPGetOverlappedResult. Un fournisseur de services peut effectuer cette opération comme il le souhaite tant qu’il interagit correctement avec le comportement de WPUCompleteOverlappedRequest . La description suivante présente une implémentation classique :

Au début du traitement qui se chevauche, le fournisseur de services définit Interne sur WSS_OPERATION_IN_PROGRESS.

Une fois l’opération d’E/S terminée, le fournisseur définit OffsetHigh sur le code d’erreur Windows Sockets 2 résultant de l’opération, définit Offset sur les indicateurs résultant de l’opération d’E/S et appelle WPUCompleteOverlappedRequest, en passant le nombre d’octets de transfert comme l’un des paramètres. WPUCompleteOverlappedRequest finit par définir InternalHigh sur le nombre d’octets de transfert, puis définit Internal sur une valeur autre que WSS_OPERATION_IN_PROGRESS.

Lorsque LPWSPGetOverlappedResult est appelé, le fournisseur de services vérifie Interne. S’il est WSS_OPERATION_IN_PROGRESS, le fournisseur attend le handle d’événement dans le membre hEvent ou retourne une erreur, en fonction du paramètre de l’indicateur fWait de LPWSPGetOverlappedResult. S’il n’est pas en cours ou après l’achèvement de l’attente, le fournisseur retourne les valeurs de InternalHigh, OffsetHigh et Offset comme nombre de transferts, code d’erreur de résultat de l’opération et indicateurs respectivement.

Configuration requise

Condition requise	Valeur
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