FltCancellableWaitForMultipleObjects-Funktion (fltkernel.h)

Artikel
04/03/2024

FltCancellableWaitForMultipleObjects führt einen abbruchfähigen Wartevorgang (eine Wartezeit, die beendet werden kann) für ein oder mehrere Dispatcherobjekte aus.

Syntax

NTSTATUS FLTAPI FltCancellableWaitForMultipleObjects(
  [in]           ULONG              Count,
  [in]           PVOID []           ObjectArray,
  [in]           WAIT_TYPE          WaitType,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PKWAIT_BLOCK       WaitBlockArray,
  [in]           PFLT_CALLBACK_DATA CallbackData
);

Parameter

[in] Count

Die Anzahl der Objekte, auf die gewartet werden soll.

[in] ObjectArray

Ein Zeiger auf ein Array von Zeigern auf Verteilerobjekte (Ereignisse, Mutexe, Semaphore, Threads und Timer), für die der Aufrufer den Speicher bereitstellt.

[in] WaitType

Eine Enumeration mit dem Wert von WaitAll, der angibt, dass alle angegebenen Objekte einen Signalzustand erreichen müssen, bevor die Wartezeit erfüllt ist; oder WaitAny, die angibt, dass eines der Objekte einen Signalzustand erreichen muss, bevor die Wartezeit erfüllt ist.

[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 eines oder alle Dispatcherobjekte auf den signalierten Zustand festgelegt sind.

Ein positiver Wert gibt eine absolute Zeit im Verhältnis zum 1. Januar 1601 an. Ein negativer Wert gibt ein Intervall relativ zur aktuellen Zeit an. Absolute Ablaufzeiten verfolgen alle Änderungen in der Systemzeit; relative Ablaufzeiten werden von Systemzeitänderungen nicht beeinflusst.

Wenn Timeout angegeben wird, wird die Wartezeit automatisch erfüllt, wenn keine der angegebenen Wartebedingungen erfüllt ist, 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] WaitBlockArray

Wenn Count <= THREAD_WAIT_OBJECTS, kann WaitBlockArray NULL sein. Andernfalls muss dieser Parameter auf einen Speicherpuffer von sizeof(KWAIT_BLOCK) * Count Bytes verweisen. Die Routine verwendet diesen Puffer für die Aufzeichnungsverwaltung während der Ausführung des Wartevorgangs.

[in] 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. Dieser Parameter ist optional und kann NULL sein. 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 die FltSetCancelCompletion-Funktion für den E/A-Vorgang nicht aufgerufen worden sein). Beachten Sie, dass callbackData vom Aufrufer gespeichert werden muss, da es nicht an einen Treiber auf niedrigerer Ebene übergeben werden kann.

Rückgabewert

FltCancellableWaitForMultipleObjects kann einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Aufrufer, der WaitAll für den WaitType-Parameter angegeben hat, und alle Dispatcherobjekte im ObjectArray-Array wurden auf den signalierten Zustand festgelegt.
STATUS_TIMEOUT	Ein Timeout ist aufgetreten, bevor der angegebene Satz von Wartebedingungen erfüllt wurde. Dieser Wert kann auch zurückgegeben werden, wenn der angegebene Satz von Wartebedingungen nicht sofort erfüllt werden kann und timeout auf 0 festgelegt ist.
STATUS_WAIT_0 bis STATUS_WAIT_63	Der aufrufer angegebene WaitAny für WaitType und eines der Dispatcherobjekte im ObjectArray-Array wurde auf den signalierten Zustand festgelegt. Die unteren sechs Bits des Rückgabewerts codieren den nullbasierten Index des Objekts, das die Wartezeit erfüllt hat.
STATUS_ABANDONED_WAIT_0 bis STATUS_ABANDONED_WAIT_63	Der Aufrufer hat versucht, auf einen Mutex zu warten, der verlassen wurde. Die unteren sechs Bits des Rückgabewerts codieren den nullbasierten Index des Mutex im ObjectArray-Array .
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 , der einem IRP-basierten Vorgang entspricht, an FltCancellableWaitForMultipleObjects übergeben wird und die E/A von einer Routine wie FltCancelIo abgebrochen wurde.
STATUS_THREAD_IS_TERMINATING	Die Wartezeit wurde unterbrochen, weil eine Anwendung oder der Benutzer den Thread beendet hat.

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

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

Hinweise

FltCancellableWaitForMultipleObjects führt einen abbruchfähigen Wartevorgang für Dispatcherobjekte aus. Wenn der Benutzer oder die Anwendung den Thread beendet oder ein E/A-Vorgang, der dem Thread zugeordnet ist, 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 kann ein Redirector einen oder mehrere sekundäre E/A-Vorgänge erstellen, um eine E/A im Benutzermodus zu verarbeiten und synchron auf den Abschluss der sekundären Anforderungen zu warten. Eine Möglichkeit besteht darin, ein Ereignis einzurichten, das von der Abschlussroutine der sekundären E/A-Vorgänge signalisiert wird, und dann auf das Signal des Ereignisses zu warten. Um dann einen abbruchfähigen Wartevorgang auszuführen, wird FltCancellableWaitForMultipleObjects aufgerufen und übergibt die Ereignisse, die den sekundären E/A-Vorgängen zugeordnet sind, 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.

Jedes Threadobjekt verfügt über ein integriertes Array von Warteblöcken, mit denen Sie auf mehrere Objekte gleichzeitig warten können. Wenn möglich, sollten Sie das integrierte Array von Warteblöcken in einem mehrfachen Wartevorgang verwenden, da kein zusätzlicher Warteblockspeicher zugeordnet und später aufgehoben werden muss. Wenn die Anzahl der Objekte, auf die Sie gleichzeitig warten müssen, jedoch größer ist als die Anzahl der integrierten Warteblöcke, verwenden Sie den WaitBlockArray-Parameter , um einen alternativen Satz von Warteblöcken anzugeben, die im Wartevorgang verwendet werden sollen. Treiber müssen nur einen ausreichend großen Speicherpuffer für WaitBlockArray zuweisen. Sie müssen den Puffer nicht initialisieren, und die Treiber können ihn als undurchsichtige Struktur behandeln. Sie können den Puffer freigeben, sobald die Routine zurückgegeben wird.

Wenn Count größer als MAXIMUM_WAIT_OBJECTS ist oder WaitBlockArray NULL und Count größer als THREAD_WAIT_OBJECTS ist, gibt das System Fehlerprüfung 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED aus.

Ein besonderer Aspekt gilt, wenn eines oder mehrere der Elemente im ObjectArray-Parameter , das an FltCancellableWaitForMultipleObjects übergeben wird, auf einen Mutex verweist. Wenn das Verteilerobjekt, auf das gewartet wird, ein Mutex ist, ist die APC-Übermittlung identisch mit allen anderen Verteilerobjekten während der Wartezeit. Sobald FltCancellableWaitForMultipleObjects 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.

Die FltCancellableWaitForMultipleObjects-Routine muss am IRQL-PASSIVE_LEVEL aufgerufen werden, wenn der CallbackData-Parameter 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.

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

Anforderungen

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