Fonction QueueUserAPC (processthreadsapi.h)

  • Article

Ajoute un objet d’appel de procédure asynchrone en mode utilisateur (APC) à la file d’attente APC du thread spécifié.

Syntaxe

DWORD QueueUserAPC(
  [in] PAPCFUNC  pfnAPC,
  [in] HANDLE    hThread,
  [in] ULONG_PTR dwData
);

Paramètres

[in] pfnAPC

Pointeur vers la fonction APC fournie par l’application à appeler lorsque le thread spécifié effectue une opération d’attente alertable. Pour plus d’informations, consultez Fonction de rappel PAPCFUNC.

[in] hThread

Handle pour le thread. Le handle doit avoir le droit d’accès THREAD_SET_CONTEXT . Pour plus d’informations, consultez Synchronisation Des droits d’accès et de sécurité des objets.

[in] dwData

Valeur unique transmise à la fonction APC pointée par le paramètre pfnAPC .

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. Windows Server 2003 et Windows XP : Aucune valeur d’erreur n’est définie pour cette fonction qui peut être récupérée en appelant GetLastError.

Remarques

Consultez la fonction QueueUserAPC2 pour plus d’informations sur les API en mode utilisateur spéciales.

La prise en charge d’APC fournie dans le système d’exploitation permet à une application de mettre en file d’attente un objet APC vers un thread. Pour garantir l’exécution réussie des fonctions utilisées par l’APC, les API doivent être mis en file d’attente uniquement vers les threads dans le processus de l’appelant.

Notes

La mise en file d’attente d’API vers des threads en dehors du processus de l’appelant n’est pas recommandée pour plusieurs raisons. Le rebasage de DLL peut entraîner des adresses incorrectes des fonctions utilisées par l’APC lorsque les fonctions sont exécutées en dehors du processus de l’appelant. De même, si un processus 64 bits met en file d’attente un APC vers un processus 32 bits ou inversement, les adresses sont incorrectes et l’application se bloque. D’autres facteurs peuvent empêcher l’exécution réussie de la fonction, même si l’adresse est connue.

Chaque thread a sa propre file d’attente APC. La mise en file d’attente d’un APC est une demande pour que le thread appelle la fonction APC. Le système d’exploitation émet une interruption logicielle pour diriger le thread pour appeler la fonction APC.

Lorsqu’un APC en mode utilisateur est mis en file d’attente, le thread n’est pas dirigé vers l’appel de la fonction APC, sauf s’il est dans un état alertable. Une fois que le thread est dans un état alertable, le thread gère tous les API en attente dans l’ordre FIFO (premier entré, premier sorti), et l’opération d’attente retourne WAIT_IO_COMPLETION. Un thread entre dans un état d’alerte à l’aide de la fonction SleepEx, de la fonction SignalObjectAndWait, de la fonction WaitForSingleObjectEx, de la fonction WaitForMultipleObjectsEx ou de la fonction MsgWaitForMultipleObjectsEx.

Si une application met en file d’attente un APC avant que le thread ne commence à s’exécuter, le thread commence par appeler la fonction APC. Une fois que le thread a appelé une fonction APC, il appelle les fonctions APC pour tous les API de sa file d’attente APC.

Il est possible de dormir ou d’attendre un objet dans l’APC. Si vous effectuez une attente alertable à l’intérieur d’un APC, il répartit de manière récursive les API. Cela peut entraîner un dépassement de capacité de la pile.

Lorsque le thread est arrêté à l’aide de la fonction ExitThread ou de la fonction TerminateThread , les APC de sa file d’attente APC sont perdus. Les fonctions APC ne sont pas appelées.

Lorsque le thread est en cours d’arrêt, l’appel de QueueUserAPC pour l’ajouter à la file d’attente APC du thread échoue avec (31) ERROR_GEN_FAILURE.

Notez que les fonctions ReadFileEx, SetWaitableTimer et WriteFileEx sont implémentées à l’aide d’un APC comme mécanisme de rappel de notification d’achèvement.

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0400 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête processthreadsapi.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi