FltCancellableWaitForSingleObject-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltCancellableWaitForSingleObject Routine führt einen abbruchbaren Wartevorgang (eine Wartezeit, die beendet werden kann) für ein Dispatcherobjekt aus.

Syntax

NTSTATUS FLTAPI FltCancellableWaitForSingleObject(
  [in]           PVOID              Object,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PFLT_CALLBACK_DATA CallbackData
);

Parameter

[in] Object

Ein Zeiger auf ein initialisiertes Dispatcherobjekt (Ereignis, Mutex, Semaphor, Thread oder Timer), für das der Aufrufer den Speicher bereitstellt.

[in, optional] Timeout

Ein Zeiger auf einen optionalen Timeoutwert. Dieser Parameter gibt die absolute oder relative Zeit in 100 Nanosekundeneinheiten an, wenn die Wartezeit abgeschlossen werden soll.

Wenn Timeout auf einen Nullwert zeigt (d. h. *Timeout == 0), wird die Routine ohne Warten zurückgegeben. Wenn der Aufrufer einen NULL-Zeiger bereitstellt (d. h. Timeout == NULL), wartet die Routine unbegrenzt, bis das Objekt auf den signalierten Zustand festgelegt ist.

Ein positiver Timeout-wert gibt eine absolute Zeit relativ zum 1. Januar 1601 an. Ein negativer Timeout-wert gibt ein Intervall relativ zur aktuellen Uhrzeit an. Absolute Ablaufzeiten verfolgen alle Änderungen in der Systemzeit. Relative Ablaufzeiten sind von Systemzeitänderungen nicht betroffen.

Wenn Timeout- angegeben ist, wird die Wartezeit automatisch erfüllt, wenn das Objekt nicht auf den signalierten Zustand festgelegt ist, wenn das angegebene Intervall abläuft.

Ein Timeoutwert von Null (d. h. *Timeout == 0) ermöglicht es Ihnen, eine Reihe von Wartezeitbedingungen zu testen und alle zusätzlichen Aktionen bedingt auszuführen, wenn die Wartezeit sofort erfüllt werden kann, wie beim Erwerb eines Mutex.

[in, optional] CallbackData

Ein Zeiger auf die FLT_CALLBACK_DATA-Struktur, die den vom Benutzer ausgegebenen E/A-Vorgang darstellt und die vom Benutzer abgebrochen werden kann. Der Aufrufer muss sicherstellen, dass der E/A-Vorgang für die Dauer dieser Routine gültig bleibt und dass die E/A keinen Abbruchroutinsatz aufweisen darf (z. B. ein FltSetCancelCompletion--Funktion darf nicht für den E/A-Vorgang aufgerufen worden sein). Beachten Sie, dass der Aufrufer die CallbackData-enthalten muss; sie kann nicht an einen Treiber auf niedrigerer Ebene übergeben werden.

Rückgabewert

FltCancellableWaitForSingleObject kann einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Das Dispatcherobjekt, das vom parameter Object angegeben wird, wurde auf den signalierten Zustand festgelegt.
STATUS_TIMEOUT	Ein Timeout ist aufgetreten, bevor das Objekt auf einen signalgesteuerten Zustand festgelegt wurde. Dieser Wert kann auch zurückgegeben werden, wenn die angegebene Wartebedingung nicht sofort erfüllt werden kann, und Timeout- auf Null festgelegt ist.
STATUS_ABANDONED_WAIT_0	Der Aufrufer hat versucht, auf einen Mutex zu warten, der abgebrochen wurde.
STATUS_CANCELLED	Die Wartezeit wurde durch eine ausstehende Abbruchanforderung für den E/A-Vorgang unterbrochen. Beachten Sie, dass dieser Wert nur zurückgegeben wird, wenn CallbackData- einem IRP-basierten Vorgang entspricht, an FltCancellableWaitForSingleObject übergeben wird und die E/A von einer Routine wie FltCancelIoabgebrochen wurde.
STATUS_THREAD_IS_TERMINATING	Die Wartezeit wurde unterbrochen, da die Anwendung oder der Benutzer den Thread beendet hat.

Der Rückgabewert gibt nur den Status der Wartezeit an.

Beachten Sie, dass das NT_SUCCESS Makro FALSCH ("Fehler") für die STATUS_CANCELLED und STATUS_THREAD_IS_TERMINATING Statuswerte und WAHR ("Erfolg") für alle anderen Statuswerte zurückgibt.

Bemerkungen

Die FltCancellableWaitForSingleObject Routine führt einen abbruchbaren Wartevorgang für ein Dispatcherobjekt aus. Wenn der Benutzer oder die Anwendung den Thread beendet oder eine dem Thread zugeordnete E/A-Datei von einer Routine wie FltCancelIoabgebrochen wurde, wird die Wartezeit abgebrochen.

Die Routine wurde entwickelt, um die E/A-Vervollständigungs-/Abbruchrichtlinienzu unterstützen. Ziel dieser Richtlinien ist es, Benutzern das schnelle Beenden von Anwendungen zu ermöglichen. Dies wiederum erfordert, dass Anwendungen die Möglichkeit haben, Threads, die E/A- und aktuelle E/A-Vorgänge ausführen, schnell zu beenden. Diese Routine bietet eine Möglichkeit, um Benutzerthreads zu blockieren (d. h. warten) im Kernel für E/A-Vervollständigung, Verteilerobjekte oder Synchronisierungsvariablen so zu blockieren, dass die Wartezeit sofort abgebrochen werden kann. Diese Routine ermöglicht auch, dass die Wartezeit des Threads beendet wird, wenn der Thread von einem Benutzer oder einer Anwendung beendet wird.

Ein Umleitungsmodul muss z. B. möglicherweise einen sekundären E/A-Vorgang erstellen, um eine Benutzermodus-E/A zu verarbeiten und synchron zu warten, bis die sekundäre Anforderung abgeschlossen ist. Eine Möglichkeit hierfür ist das Einrichten eines Ereignisses, das durch die Abschlussroutine des sekundären E/A-Vorgangs signalisiert wird, und dann auf das Signal des Ereignisses warten. Um dann einen abbruchbaren Wartevorgang auszuführen, wird FltCancellableWaitForSingleObject aufgerufen, das dem sekundären E/A-Vorgang zugeordnete Ereignis und den ursprünglichen Benutzermodus-E/A-Vorgang zu übergeben. Die Wartezeit des Threads, bis das Ereignis signalisiert wird, wird abgebrochen, wenn ein ausstehendes Beendigungsereignis auftritt oder der ursprüngliche Benutzermodus-E/A-Vorgang abgebrochen wird.

Beachten Sie, dass das Beenden der Wartezeit keinen E/A-Vorgang, der vom Anrufer ausgegeben wurde, automatisch abbricht – die separat vom Anrufer behandelt werden muss.

Eine besondere Berücksichtigung gilt, wenn der an FltCancellableWaitForSingleObject übergebene parameter Object ein Mutex ist. Wenn das dispatcher-Objekt, auf das gewartet wird, ein Mutex ist, ist die APC-Zustellung identisch mit allen anderen Dispatcherobjekten während der Wartezeit. Sobald FltCancellableWaitForSingleObject jedoch mit STATUS_SUCCESS zurückgegeben wird und der Thread tatsächlich den Mutex enthält, werden nur spezielle Kernelmodus-APCs bereitgestellt. Die Übermittlung aller anderen APCs, sowohl vom Kernelmodus als auch vom Benutzermodus, ist deaktiviert. Diese Einschränkung für die Bereitstellung von APCs bleibt bestehen, bis der Mutex freigegeben wird.

Ein Mutex kann rekursiv nur MINLONG-Zeiten erworben werden. Wenn dieser Grenzwert überschritten wird, löst die Routine eine STATUS_MUTANT_LIMIT_EXCEEDED Ausnahme aus.

FltCancellableWaitForSingleObject- muss bei IRQL-PASSIVE_LEVEL aufgerufen werden, wenn der parameter CallbackData einen gültigen Filter-Manager-IRP darstellt. Andernfalls kann die Routine bei IRQL kleiner oder gleich APC_LEVEL aufgerufen werden. Normale Kernel-APCs können bei Bedarf vom Aufrufer deaktiviert werden, indem die KeEnterCriticalRegion oder FsRtlEnterFileSystem Routinen aufgerufen werden. Spezielle Kernel-APCs dürfen jedoch nicht deaktiviert werden.

Die FltCancellableWaitForSingleObject Routine wird auf Debugbuilds bestätigt, wenn die CallbackData- einen Filter-Manager-IRP-Vorgang darstellt, aber die IRP in der CallbackData- Struktur NULL ist.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista
Zielplattform-	Universal
Header-	fltkernel.h (include Fltkernel.h, Ntifs.h)
Library	Fltmgr.lib
DLL-	Fltmgr.sys
IRQL-	Siehe Abschnitt "Hinweise".