QueueUserAPC-Funktion (processthreadsapi.h)

  • Artikel

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

Syntax

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

Parameter

[in] pfnAPC

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 PAPCFUNC-Rückruffunktion.

[in] hThread

Ein Handle auf den Thread. Das Handle muss über das zugriffsrecht THREAD_SET_CONTEXT verfügen. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.

[in] dwData

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

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. Windows Server 2003 und Windows XP: Für diese Funktion sind keine Fehlerwerte definiert, die durch Aufrufen von GetLastError abgerufen werden können.

Hinweise

Informationen zu speziellen Benutzermodus-APCs finden Sie unter QueueUserAPC2-Funktion .

Die im Betriebssystem bereitgestellte APC-Unterstützung ermöglicht es einer Anwendung, ein APC-Objekt in eine Warteschlange in einen Thread zu stellen. Um die erfolgreiche Ausführung der vom APC verwendeten Funktionen sicherzustellen, sollten APCs nur in die Threads im Prozess des Aufrufers eingereiht werden.

Hinweis

Das Anstehen von APCs zu Threads außerhalb des Aufrufprozesses wird aus verschiedenen Gründen nicht empfohlen. Die DLL-Neubasierung kann dazu führen, dass die Adressen von Funktionen, die vom APC verwendet werden, falsch sind, wenn die Funktionen außerhalb des Prozesses des Aufrufers ausgeführt werden. Wenn ein 64-Bit-Prozess einen APC in die Warteschlange eines 32-Bit-Prozesses stellt oder umgekehrt, sind die Adressen falsch, und die Anwendung stürzt ab. Andere Faktoren können die erfolgreiche Funktionsausführung verhindern, auch wenn die Adresse bekannt ist.

Jeder Thread verfügt über eine eigene APC-Warteschlange. Die Warteschlange eines APC ist eine Anforderung an den Thread zum Aufrufen der APC-Funktion. Das Betriebssystem gibt einen Software-Interrupt aus, um den Thread anweisen, die APC-Funktion aufzurufen.

Wenn ein Benutzermodus-APC in die Warteschlange eingereiht wird, wird der Thread nicht zum Aufrufen der APC-Funktion weitergeleitet, es sei denn, sie befindet sich in einem warnbaren Zustand. Nachdem sich der Thread in einem warnbaren Zustand befindet, verarbeitet der Thread alle ausstehenden APCs in fiFO-Reihenfolge (first in, first out), und der Wartevorgang gibt WAIT_IO_COMPLETION zurück. Ein Thread wechselt mit der SleepEx-Funktion, der SignalObjectAndWait-Funktion, der WaitForSingleObjectEx-Funktion, der WaitForMultipleObjectsEx-Funktion oder der MsgWaitForMultipleObjectsEx-Funktion in einen warnbaren Zustand.

Wenn eine Anwendung einen APC in die Warteschlange stellt, bevor der Thread ausgeführt wird, ruft der Thread zunächst die APC-Funktion auf. Nachdem der Thread eine APC-Funktion aufgerufen hat, ruft er die APC-Funktionen für alle APCs in seiner APC-Warteschlange auf.

Es ist möglich, im APC auf ein Objekt zu warten oder in den Ruhezustand zu versetzen. Wenn Sie eine warnbare Wartezeit innerhalb eines APC ausführen, werden die APCs rekursiv verteilt. Dies kann zu einem Stapelüberlauf führen.

Wenn der Thread mit der ExitThread - oder TerminateThread-Funktion beendet wird, gehen die APCs in der APC-Warteschlange verloren. Die APC-Funktionen werden nicht aufgerufen.

Wenn der Thread beendet wird, schlägt das Aufrufen von QueueUserAPC zum Hinzufügen zur APC-Warteschlange des Threads mit (31) ERROR_GEN_FAILURE fehl.

Beachten Sie, dass die Funktionen ReadFileEx, SetWaitableTimer und WriteFileEx mithilfe eines APC als Vervollständigungsbenachrichtigungsrückrufmechanismus implementiert werden.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0400 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile processthreadsapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch