FltCancellableWaitForSingleObject-Funktion (fltkernel.h)

Artikel
02/29/2024

Die FltCancellableWaitForSingleObject-Routine führt einen abbruchfähigen Wartevorgang (eine Wartezeit, die beendet werden kann) für ein Verteilerobjekt 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, zu der die Wartezeit abgeschlossen werden soll.

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

Ein positiver Timeoutwert gibt eine absolute Zeit relativ zum 1. Januar 1601 an. Ein negativer Timeoutwert gibt ein Intervall relativ zur aktuellen Zeit an. Absolute Ablaufzeiten verfolgen alle Änderungen an der Systemzeit. Relative Ablaufzeiten werden von Systemzeitänderungen nicht beeinflusst.

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

Mit einem Timeoutwert von 0 (d. h. *Timeout == 0) können Sie eine Reihe von Wartebedingungen testen und alle zusätzlichen Aktionen bedingt ausführen, wenn die Wartezeit sofort erfüllt werden kann, wie beim Abrufen eines Mutex.

[in, optional] CallbackData

Ein Zeiger auf die FLT_CALLBACK_DATA Struktur, die den E/A-Vorgang darstellt, der vom Benutzer ausgegeben wurde und 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 für die E/A kein Abbruchroutinensatz festgelegt sein darf (z. B. darf keine FltSetCancelCompletion-Funktion für den E/A-Vorgang aufgerufen worden sein). Beachten Sie, dass der Aufrufer die Rückrufdaten 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 vom Object-Parameter angegebene Dispatcherobjekt wurde auf den signalierten Zustand festgelegt.
STATUS_TIMEOUT	Ein Timeout ist aufgetreten, bevor das Objekt auf einen Signalzustand festgelegt wurde. Dieser Wert kann auch zurückgegeben werden, wenn die angegebene Wartebedingung nicht sofort erfüllt werden kann und timeout auf 0 festgelegt ist.
STATUS_ABANDONED_WAIT_0	Der Aufrufer hat versucht, auf einen Mutex zu warten, der verlassen 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, der an FltCancellableWaitForSingleObject übergeben wird und die E/A von einer Routine wie FltCancelIo abgebrochen wurde.
STATUS_THREAD_IS_TERMINATING	Die Wartezeit wurde unterbrochen, weil die Anwendung oder der Benutzer den Thread beendet hat.

Der Rückgabewert gibt nur die status der Wartezeit an.

Beachten Sie, dass das NT_SUCCESS-Makro FALSE ("Fehler") für die STATUS_CANCELLED- und STATUS_THREAD_IS_TERMINATING status-Werte und TRUE ("success") für alle anderen status-Werte zurückgibt.

Hinweise

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

Die Routine ist so konzipiert, dass sie die E/A-Abschluss-/Abbruchrichtlinien unterstützt. Ziel dieser Richtlinien ist es, Benutzern das schnelle Beenden von Anwendungen zu ermöglichen. Dies wiederum erfordert, dass Anwendungen in der Lage sind, Threads, die E/A und alle aktuellen E/A-Vorgänge ausführen, schnell zu beenden. Diese Routine bietet eine Möglichkeit für Benutzerthreads, im Kernel für E/A-Vervollständigung, Dispatcherobjekte oder Synchronisierungsvariablen zu blockieren (d. h. warten), sodass die Wartezeit problemlos abgebrochen werden kann. Diese Routine ermöglicht auch, dass das Warten des Threads beendet wird, wenn der Thread von einem Benutzer oder einer Anwendung beendet wird.

Beispielsweise muss ein Redirector möglicherweise einen sekundären E/A-Vorgang erstellen, um eine E/A im Benutzermodus zu verarbeiten und synchron auf den Abschluss der sekundären Anforderung zu warten. Eine Möglichkeit besteht darin, ein Ereignis einzurichten, das von der Abschlussroutine des sekundären E/A-Vorgangs signalisiert wird, und dann auf das Signal des Ereignisses zu warten. Um dann einen abbruchfähigen Wartevorgang auszuführen, wird FltCancellableWaitForSingleObject aufgerufen und übergibt das Ereignis, das dem sekundären E/A-Vorgang zugeordnet ist, und den ursprünglichen Benutzermodus-E/A-Vorgang. Das Warten des Threads auf das Signal des Ereignisses wird abgebrochen, wenn ein Ausstehendes Beendigungsereignis auftritt oder wenn der ursprüngliche E/A-Vorgang im Benutzermodus abgebrochen wird.

Beachten Sie, dass das Beenden der Wartezeit nicht automatisch alle E/A-Vorgänge abbricht, die vom Aufrufer ausgegeben wurden. Dies muss separat vom Aufrufer behandelt werden.

Ein besonderer Aspekt gilt, wenn der anFltCancellableWaitForSingleObject übergebene Object-Parameter ein Mutex ist. Wenn das Verteilerobjekt, auf das gewartet wird, ein Mutex ist, ist die APC-Übermittlung identisch mit allen anderen Verteilerobjekten während der Wartezeit. Sobald FltCancellableWaitForSingleObject jedoch mit STATUS_SUCCESS zurückgibt und der Thread tatsächlich den Mutex enthält, werden nur spezielle Kernelmodus-APCs bereitgestellt. Die Übermittlung aller anderen APCs, sowohl im Kernelmodus als auch im Benutzermodus, ist deaktiviert. Diese Einschränkung für die Bereitstellung von APCs bleibt bestehen, bis der Mutex freigegeben wird.

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

FltCancellableWaitForSingleObject muss am 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 Routinen KeEnterCriticalRegion oder FsRtlEnterFileSystem aufgerufen werden. Spezielle Kernel-APCs dürfen jedoch nicht deaktiviert werden.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Zielplattform	Universell
Header	fltkernel.h (include Fltkernel.h, Ntifs.h)
Bibliothek	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.