WSAGetOverlappedResult, fonction (winsock2.h)

Article
08/27/2023

La fonction WSAGetOverlappedResult récupère les résultats d’une opération qui se chevauche sur le socket spécifié.

Syntaxe

BOOL WSAAPI WSAGetOverlappedResult(
  [in]  SOCKET          s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD         lpcbTransfer,
  [in]  BOOL            fWait,
  [out] LPDWORD         lpdwFlags
);

Paramètres

[in] s

Descripteur identifiant le socket.

Il s’agit du même socket que celui qui a été spécifié lorsque l’opération chevauchée a été démarrée par un appel à l’une des fonctions Winsock qui prend en charge les opérations qui se chevauchent. Ces fonctions incluent AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets, WSARecv , WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg),WSASend, WSASendMsg, WSASendMsg, WSASendTo et WSAIoctl.

[in] lpOverlapped

Pointeur vers une structure WSAOVERLAPPED qui a été spécifiée lors du démarrage de l’opération chevauchée. Ce paramètre ne doit pas être un pointeur NULL .

[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 la fonction WSAIoctl . Ce paramètre ne doit pas être un pointeur NULL .

[in] fWait

Indicateur qui spécifie si la fonction doit attendre la fin de l’opération superposée en attente. Si la valeur est TRUE, la fonction ne retourne pas tant que l’opération n’est pas terminée. Si FALSE et que l’opération est toujours en attente, la fonction retourne FALSE et la fonction WSAGetLastError retourne WSA_IO_INCOMPLETE. Le paramètre fWait peut être défini sur TRUE uniquement si l’opération qui se chevauche a sélectionné la 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 chevauchée a été lancée via WSARecv ou WSARecvFrom, ce paramètre contient la valeur des résultats pour le paramètre lpFlags . Ce paramètre ne doit pas être un pointeur NULL .

Valeur retournée

Si WSAGetOverlappedResult réussit, la valeur de retour est TRUE. Cela signifie que l’opération qui se chevauche s’est terminée correctement et que la valeur pointée par lpcbTransfer a été mise à jour.

Si WSAGetOverlappedResult retourne FALSE, cela signifie que l’opération qui se chevauche n’est pas terminée, que l’opération qui se chevauche est terminée mais avec des erreurs, ou que la status d’achèvement de l’opération qui se chevauche n’a pas pu être déterminée en raison d’erreurs dans un ou plusieurs paramètres dans WSAGetOverlappedResult. En cas d’échec, la valeur pointée par lpcbTransfer n’est pas mise à jour. Utilisez WSAGetLastError pour déterminer la cause de l’échec (soit par la fonction WSAGetOverlappedResult , soit par l’opération superposée associée).

Code d'erreur	Signification
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENOTSOCK	Le descripteur n’est pas un socket.
WSA_INVALID_HANDLE	Le paramètre hEvent de la structure WSAOVERLAPPED ne contient pas de handle d’objet d’événement valide.
WSA_INVALID_PARAMETER	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.
WSAEFAULT	Un ou plusieurs paramètres lpOverlapped, lpcbTransfer ou lpdwFlags ne se trouvent pas dans une partie valide de l’espace d’adressage utilisateur. Cette erreur est retournée si le paramètre lpOverlapped, lpcbTransfer ou lpdwFlags était un pointeur NULL sur Windows Server 2003 et versions antérieures.

Remarques

La fonction WSAGetOverlappedResult signale les résultats de l’opération superposée spécifiée dans le paramètre lpOverlapped pour le socket spécifié dans le paramètre s . La fonction WSAGetOverlappedResult reçoit le descripteur de socket et la structure WSAOVERLAPPED qui a été spécifiée lors de l’appel de la fonction superposée. Une opération en attente est indiquée lorsque la fonction qui a démarré l’opération retourne FALSE et que la fonction WSAGetLastError retourne WSA_IO_PENDING. Lorsqu’une opération d’E/S telle que WSARecv 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 d’événement à l’état signalé.

Si le paramètre fWait a la valeur TRUE, WSAGetOverlappedResult détermine si l’opération en attente a été terminée en attendant que l’objet d’événement soit à l’état signalé. Un client peut définir le paramètre fWait sur TRUE, mais 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 paramètre hEvent de la structure WSAOVERLAPPED est différente et la définition de fWait sur TRUE entraîne des résultats imprévisibles.

Si la fonction WSAGetOverlappedResult est appelée avec le paramètre lpOverlapped, lpcbTransfer ou lpdwFlags défini sur un pointeur NULL sur Windows Vista, cela entraîne une violation d’accès. Si la fonction WSAGetOverlappedResult est appelée avec le paramètre lpOverlapped, lpcbTransfer ou lpdwFlags défini sur un pointeur NULL sur Windows Server 2003 et versions antérieures, le code d’erreur WSAEFAULT est retourné.

Note Toutes les E/S sont annulées lorsqu’un thread se ferme. 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 .

Windows Phone 8 : cette fonction est prise en charge pour les applications Windows Phone Store sur Windows Phone 8 et versions ultérieures.

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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll