Fonction WPUQueueApc (ws2spi.h)

  • Article

La fonction WPUQueueApc met en file d’attente un appel de procédure asynchrone en mode utilisateur (APC) vers le thread spécifié afin de faciliter l’appel des routines d’achèvement d’E/S qui se chevauchent.

Syntaxe

int WPUQueueApc(
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPWSAUSERAPC  lpfnUserApc,
  [in]  DWORD_PTR     dwContext,
  [out] LPINT         lpErrno
);

Paramètres

[in] lpThreadId

Pointeur vers une structure WSATHREADID qui identifie le contexte de thread. Un pointeur vers cette structure est fourni au fournisseur de services par le Ws2_32.dll en tant que paramètre d’entrée vers une opération qui se chevauche. Le fournisseur doit stocker la structure WSATHREADID localement et fournir un pointeur vers ce magasin local. La copie locale de WSATHREADID n’est plus nécessaire une fois que WPUQueueApc est retourné.

[in] lpfnUserApc

Pointeur vers la fonction APC à appeler.

[in] dwContext

Valeur de contexte 32 bits qui est ensuite fournie en tant que paramètre d’entrée à la fonction APC.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit, WPUQueueApc retourne zéro et met en file d’attente la routine d’achèvement pour le thread spécifié. Sinon, il retourne SOCKET_ERROR, et un code d’erreur spécifique est disponible dans lpErrno.

Code d'erreur Signification
WSAEFAULT
 Le paramètre dwThreadId ne spécifie pas de thread valide.
 
 

Remarques

Cette fonction met en file d’attente une fonction APC sur le thread spécifié. Sous Windows, cela s’effectue à l’aide d’un appel de procédure asynchrone en mode utilisateur (APC). L’APC ne s’exécute que lorsque le thread spécifié est bloqué dans une attente pouvant être alertée et qu’un rappel est effectué directement. Cet appel est sécurisé pour une utilisation dans un contexte d’interruption.

LPWSAUSERAPC est défini comme suit :

typedef void ( CALLBACK FAR * LPWSAUSERAPC )( DWORD dwContext );

Étant donné que le mécanisme APC ne prend en charge qu’une seule valeur de contexte, lpfnUserApc lui-même ne peut pas être la routine d’achèvement spécifiée par le client, ce qui implique davantage de paramètres. Le fournisseur de services doit à la place fournir un pointeur vers sa propre fonction APC qui utilise la valeur dwContext 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.

Pour les fournisseurs de services où un composant en mode utilisateur implémente des E/S qui se chevauchent, une utilisation classique du mécanisme APC est la suivante.

    - Une fois l’opération d’E/S terminée, le fournisseur alloue une petite mémoire tampon et l’empaque avec un pointeur vers la procédure d’achèvement fournie par le client et les valeurs de paramètres à passer à la procédure. - Il met en file d’attente un APC, en spécifiant le pointeur vers la mémoire tampon comme valeur dwContext et sa propre procédure intermédiaire en tant que procédure cible lpfnUserApc. - Lorsque le thread cible passe finalement à l’état d’attente pouvant être alerté, la procédure intermédiaire du fournisseur de services est appelée dans le contexte de thread approprié. - La procédure intermédiaire décompresse simplement les paramètres, libère la mémoire tampon et appelle la procédure d’achèvement fournie par le client.

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]
Plateforme cible Windows
En-tête ws2spi.h

Voir aussi

WSATHREADID

LPWSPIoctl

LPWSPRecv

LPWSPRecvFrom

LPWSPSend

LPWSPSendTo