FltCancellableWaitForMultipleObjects-Funktion (fltkernel.h)
Die FltCancellableWaitForMultipleObjects führt einen abbruchbaren 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 Dispatcherobjekte (Ereignisse, Mutexes, Semaphore, Threads und Timer), für die der Aufrufer den Speicher bereitstellt.
[in] WaitType
Eine Aufzählung mit dem Wert einer der beiden WaitAll, die angibt, dass alle angegebenen Objekte einen signalisierten Zustand erreichen müssen, bevor die Wartezeit erfüllt ist; oder WaitAny, was angibt, dass eines der Objekte einen signalisierten Zustand 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, bei denen die Wartezeit abgeschlossen werden soll.
Wenn Timeout auf einen Nullwert verweist (d. h. *Timeout == 0), wird die Routine ohne Warten zurückgegeben. Wenn der Aufrufer einen NULL-Zeiger (d. h. Timeout == NULL) bereitstellt, wartet die Routine unbegrenzt, bis ein 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 Uhrzeit an. Absolute Ablaufzeiten verfolgen alle Änderungen der Systemzeit; Relative Ablaufzeiten sind von Systemzeitänderungen nicht betroffen.
Wenn Timeout angegeben ist, wird die Wartezeit automatisch erfüllt, wenn keine der angegebenen Wartezeitbedingungen erfüllt 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] 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 Datensatzhaltung beim Ausführen des Wartevorgangs.
[in] 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. 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 die E/A keinen Abbruchroutinsatz haben darf (z. B. FltSetCancelCompletion-Funktion darf nicht für den E/A-Vorgang aufgerufen worden sein). Beachten Sie, dass der CallbackData- vom Aufrufer gehalten werden muss, da er 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 parameter WaitType und alle Dispatcherobjekte im ObjectArray Array auf den signalierten Zustand festgelegt wurde. |
| STATUS_TIMEOUT | Ein Timeout ist aufgetreten, bevor die angegebenen Wartebedingungen erfüllt wurden. Dieser Wert kann auch zurückgegeben werden, wenn der angegebene Satz von Wartebedingungen nicht sofort erfüllt werden kann und Timeout auf Null festgelegt ist. |
| STATUS_WAIT_0 bis STATUS_WAIT_63 | Der aufrufer hat WaitAny für WaitType angegeben, 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 abgebrochen 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 FltCancelIoabgebrochen wurde. |
| STATUS_THREAD_IS_TERMINATING | Die Wartezeit wurde unterbrochen, weil eine 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
Bemerkungen
Die FltCancellableWaitForMultipleObjects führt einen abbruchbaren Wartevorgang für Dispatcherobjekte aus. Wenn der Benutzer oder die Anwendung den Thread beendet oder ein mit dem Thread verknüpfter E/A-Vorgang 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.
Beispielsweise muss ein Umleitungsmodul eine oder mehrere sekundäre E/A-Vorgänge erstellen, um eine Benutzermodus-E/A zu verarbeiten und synchron zu warten, bis die sekundären Anforderungen abgeschlossen sind. Eine Möglichkeit hierfür ist das Einrichten eines Ereignisses, das durch die Abschlussroutine der sekundären E/A-Vorgänge signalisiert wird, und dann auf das Signal des Ereignisses warten. Um dann einen abbruchbaren Wartevorgang auszuführen, wird FltCancellableWaitForMultipleObjects aufgerufen, um die Ereignisse zu übergeben, die den sekundären E/A-Vorgängen zugeordnet sind, und dem ursprünglichen Benutzermodus-E/A-Vorgang. 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.
Jedes Threadobjekt verfügt über ein integriertes Array von Warteblöcken, mit denen Sie gleichzeitig auf mehrere Objekte warten können. Wenn möglich, sollten Sie das integrierte Array von Warteblöcken in einem Wait-Multiple-Vorgang verwenden, da kein zusätzlicher Warteblockspeicher zugewiesen und später zugeordnet werden muss. Wenn jedoch die Anzahl der Objekte, auf die Sie gleichzeitig warten müssen, größer als die Anzahl der integrierten Warteblöcke ist, 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 entweder "Count" größer als MAXIMUM_WAIT_OBJECTS oder wenn WaitBlockArray- NULL ist und "Count" größer als THREAD_WAIT_OBJECTS ist, gibt das System probleme Fehlerüberprüfung 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.
Eine besondere Berücksichtigung gilt, wenn mindestens eines der Elemente im ObjectArray Parameter übergeben wird, der an FltCancellableWaitForMultipleObjects auf einen Mutex übergeben wird. 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 FltCancellableWaitForMultipleObjects 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.
Die FltCancellableWaitForMultipleObjects- Routine muss bei 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 KeEnterCriticalRegion oder FsRtlEnterFileSystem Routinen aufgerufen werden. Spezielle Kernel-APCs dürfen jedoch nicht deaktiviert werden.
FltCancellableWaitForMultipleObjects 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 Ntifs.h, Fltkernel.h) |
| Library | Fltmgr.lib |
| IRQL- | Siehe Abschnitt "Hinweise". |
Siehe auch
FltCancellableWaitForSingleObject