WpUCompleteOverlappedRequest, fonction (ws2spi.h)

Article
08/28/2023

La fonction WPUCompleteOverlappedRequest effectue une notification d’achèvement des E/S qui se chevauchent pour les opérations d’E/S qui se chevauchent.

Syntaxe

int WPUCompleteOverlappedRequest(
  [in]  SOCKET          s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [in]  DWORD           dwError,
  [in]  DWORD           cbTransferred,
  [out] LPINT           lpErrno
);

Paramètres

[in] s

Socket de fournisseur de services créé par WPUCreateSocketHandle.

[in] lpOverlapped

Pointeur vers une structure WSAOVERLAPPED associée à l’opération d’E/S superposée dont l’achèvement doit être notifié.

[in] dwError

L’achèvement status de l’opération d’E/S qui se chevauche et dont l’achèvement doit être notifié.

[in] cbTransferred

Nombre d’octets transférés vers ou depuis les mémoires tampons clientes (la direction du transfert dépend de la nature d’envoi ou de réception de l’opération d’E/S superposée dont l’achèvement doit être notifié).

[out] lpErrno

Pointeur vers le code d’erreur résultant de l’exécution de cette fonction.

Valeur retournée

Si aucune erreur ne se produit, WPUCompleteOverlappedRequest retourne zéro et notifie l’achèvement de l’opération d’E/S qui se chevauche en fonction du mécanisme sélectionné par le client (signale un événement trouvé dans la structure WSAOVERLAPPED référencée par lpOverlapped et/ou met en file d’attente un rapport d’achèvement status au port d’achèvement associé au socket si un port d’achèvement est associé). Sinon, WPUCompleteOverlappedRequest retourne SOCKET_ERROR et un code d’erreur spécifique est disponible dans lpErrno.

Code d'erreur	Signification
WSAEINVAL	Le socket passé dans le paramètre s n’est pas un socket créé par WPUCreateSocketHandle.

Remarques

La fonction WPUCompleteOverlappedRequest effectue une notification d’achèvement d’E/S qui se chevauche pour les opérations d’E/S qui se chevauchent, où le mécanisme d’achèvement spécifié par le client est autre chose que l’appel de procédure asynchrone en mode utilisateur (APC). Cette fonction ne peut être utilisée que pour les handles de socket créés par WPUCreateSocketHandle.

**Remarque** Cette fonction est différente des autres fonctions avec le préfixe « WPU » en ce qu’elle n’est pas accessible via la table upcall. Au lieu de cela, il est exporté directement par Ws2_32.dll. Les fournisseurs de services qui doivent appeler cette fonction doivent être liés à WS2_32.lib ou utiliser des fonctions de système d’exploitation appropriées telles que LoadLibrary et GetProcAddress pour récupérer le pointeur de fonction.

La fonction **WPUCompleteOverlappedRequest** est utilisée par les fournisseurs de services qui n’implémentent pas la fonctionnalité de système de fichiers installable (IFS) directement pour les handles de socket qu’ils exposent. Il effectue une notification d’achèvement pour toute demande d’E/S chevauchée pour laquelle la notification d’achèvement spécifiée est autre qu’un APC en mode utilisateur. **WPUCompleteOverlappedRequest** est pris en charge uniquement pour les handles de socket créés par WPUCreateSocketHandle et non pour les sockets créés directement par un fournisseur de services.

Si le client sélectionne un APC en mode utilisateur comme méthode de notification, le fournisseur de services doit utiliser WPUQueueApc ou une autre fonction de système d’exploitation appropriée pour effectuer la notification d’achèvement. Si le client ne sélectionne pas le mode utilisateur APC, un fournisseur de services qui n’implémente pas directement la fonctionnalité IFS ne peut pas déterminer si le client a associé ou non un port d’achèvement au handle de socket. Par conséquent, il ne peut pas déterminer si la méthode de notification d’achèvement doit mettre en file d’attente un enregistrement d’achèvement status à un port d’achèvement ou signaler un événement trouvé dans la structure WSAOVERLAPPED. L’architecture Windows Socket 2 effectue le suivi de toute association de port d’achèvement avec un socket créé par WPUCreateSocketHandle et peut prendre une décision correcte entre la notification basée sur le port d’achèvement ou la notification basée sur les événements.

Lorsque WPUCompleteOverlappedRequest met en file d’attente une indication d’achèvement, il définit le membre InternalHigh de la structure WSAOVERLAPPED sur le nombre d’octets transférés. Ensuite, il définit le membre Interne sur une valeur dépendante du système d’exploitation autre que la valeur spéciale WSS_OPERATION_IN_PROGRESS. Il peut y avoir un léger délai après le retour de WPUCompleteOverlappedRequest avant l’affichage de ces valeurs, car le traitement peut se produire de manière asynchrone. Toutefois, la valeur InternalHigh (nombre d’octets) est garantie d’être définie au moment où Internal est défini.

WPUCompleteOverlappedRequest fonctionne comme indiqué (effectue la notification d’achèvement comme demandé par le client), que le handle de socket ait été associé ou non à un port d’achèvement.

Interaction avec WSPGetOverlappedResult

Le comportement de WPUCompleteOverlappedRequest impose des contraintes sur la façon dont un fournisseur de services implémente WSPGetOverlappedResult , car seuls les membres Offset et OffsetHigh de la structure WSAOVERLAPPED sont exclusivement contrôlés par le fournisseur de services, mais trois valeurs (nombre d’octets, indicateurs et erreur) doivent être récupérées de la structure par WSPGetOverlappedResult. Un fournisseur de services peut effectuer cette opération de la manière qu’il choisit tant qu’il interagit correctement avec le comportement de WPUCompleteOverlappedRequest . Toutefois, une implémentation classique est la suivante :

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 Socket 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 WSPGetOverlappedResult 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 WSPGetOverlappedResult. 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 en tant que 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]
Plateforme cible	Windows
En-tête	ws2spi.h

Voir aussi

WPUCreateSocketHandle

WPUQueueApc

WSAOVERLAPPED

WSPGetOverlappedResult

Partager via