QueueUserAPC2-Funktion (processthreadsapi.h)

  • Artikel

Fügt der APC-Warteschlange des angegebenen Threads ein Asynchrones Prozeduraufruf -Objekt im Benutzermodus hinzu.

Syntax

BOOL QueueUserAPC2(
  PAPCFUNC             ApcRoutine,
  HANDLE               Thread,
  ULONG_PTR            Data,
  QUEUE_USER_APC_FLAGS Flags
);

Parameter

ApcRoutine

Ein Zeiger auf die von der Anwendung bereitgestellte APC-Funktion, die aufgerufen werden soll, wenn der angegebene Thread einen warnbaren Wartevorgang ausführt. Weitere Informationen finden Sie unter APCProc.

Für spezielle Benutzermodus-APCs ist keine warnbare Wartezeit erforderlich. Weitere Informationen zu speziellen Benutzermodus-APCs finden Sie unter Hinweise .

Thread

Ein Handle auf den Thread. Das Handle muss über THREAD_SET_CONTEXT Zugriffsberechtigung verfügen. Weitere Informationen finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsrechte.

Data

Ein einzelner Wert, der an die APC-Funktion übergeben wird, auf die der ApcRoutine-Parameter verweist.

Flags

Ein Wert aus QUEUE_USER_APC_FLAGS Enumeration , der das Verhalten des Benutzermodus-APC ändert.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Reguläre Benutzermodus-APCs werden nur ausgeführt, wenn sich der Zielthread in einem warnbaren Zustand befindet. Weitere Hinweise zu regulären Benutzermodus-APCs finden Sie unter QueueUserAPC-Funktion .

Spezielle Benutzermodus-APCs werden immer ausgeführt, auch wenn sich der Zielthread nicht in einem warnbaren Zustand befindet. Wenn beispielsweise der Zielthread derzeit Code im Benutzermodus ausführt oder der Zielthread derzeit eine warnbare Wartezeit ausführt, wird der Zielthread sofort für die APC-Ausführung unterbrochen. Wenn der Zielthread einen Systemaufruf ausführt oder eine nicht warnungsfähige Wartezeit ausführt, wird der APC ausgeführt, nachdem der Systemaufruf oder die Wartewarte ohne Warnung abgeschlossen ist (die Wartezeit wird nicht unterbrochen).

Da die Ausführung des speziellen Benutzermodus-APC nicht mit dem Zielthread synchronisiert wird, ist besondere Vorsicht geboten (über die normalen Anforderungen für Multithreading und Synchronisierung hinaus). Beim Abrufen von Sperren kann der unterbrochene Zielthread beispielsweise bereits besitzer der Sperre sein oder gerade dabei sein, die Sperre zu erwerben oder zu lösen. Da es außerdem keine Möglichkeiten gibt, einen Thread am Empfang spezieller Benutzermodus-APCs zu blockieren, kann ein spezieller Benutzermodus-APC für einen Zielthread ausgeführt werden, der bereits einen speziellen Benutzermodus-APC ausführt.

Derzeit werden spezielle Benutzermodus-APCs nur für native Architekturen und nicht für die Ausführung unter WoW unterstützt.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 11 (Build 22000)
Unterstützte Mindestversion (Server) Windows Server 2022 (Build 20348)
Zielplattform Windows
Kopfzeile processthreadsapi.h (einschließlich Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll