Funzione FltCancellableWaitForMultipleObjects (fltkernel.h)

Articolo
02/29/2024

FltCancellableWaitForMultipleObjects esegue un'operazione di attesa annullabile (un'attesa che può essere terminata) in uno o più oggetti dispatcher.

Sintassi

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
);

Parametri

[in] Count

Numero di oggetti da attendere.

[in] ObjectArray

Puntatore a una matrice di puntatori a oggetti dispatcher (eventi, mutex, semafori, thread e timer) per cui il chiamante fornisce l'archiviazione.

[in] WaitType

Enumerazione con il valore di WaitAll, che indica che tutti gli oggetti specificati devono ottenere uno stato segnalato prima che venga soddisfatta l'attesa; o WaitAny, che indica che uno degli oggetti deve ottenere uno stato segnalato prima che l'attesa venga soddisfatta.

[in, optional] Timeout

Puntatore a un valore di timeout facoltativo. Questo parametro specifica il tempo assoluto o relativo in 100 unità nanosecondhe a cui deve essere completata l'attesa.

Se Timeout punta a un valore zero , ovvero *Timeout == 0, la routine restituisce senza attendere. Se il chiamante fornisce un puntatore NULL ,ovvero Timeout == NULL, la routine attende in modo indefinito fino a quando uno o tutti gli oggetti dispatcher vengono impostati sullo stato segnalato.

Un valore positivo specifica un tempo assoluto, rispetto al 1° gennaio 1601. Un valore negativo specifica un intervallo relativo all'ora corrente. I tempi di scadenza assoluti tengono traccia delle modifiche apportate all'ora di sistema; le ore di scadenza relative non sono interessate dalle modifiche all'ora di sistema.

Se viene specificato timeout, l'attesa viene soddisfatta automaticamente se nessuna delle condizioni di attesa specificate viene soddisfatta quando scade l'intervallo specificato.

Un valore di timeout pari a zero , ovvero *Timeout == 0) consente di testare un set di condizioni di attesa e di eseguire in modo condizionale eventuali azioni aggiuntive se l'attesa può essere immediatamente soddisfatta, come nell'acquisizione di un mutex.

[in, optional] WaitBlockArray

Se Count <= THREAD_WAIT_OBJECTS, WaitBlockArray può essere NULL. In caso contrario, questo parametro deve puntare a un buffer di memoria di sizeof(KWAIT_BLOCK) * Count byte. La routine usa questo buffer per il mantenimento dei record durante l'esecuzione dell'operazione di attesa.

[in] CallbackData

Puntatore alla struttura FLT_CALLBACK_DATA che rappresenta l'operazione di I/O rilasciata dall'utente e che può essere annullata dall'utente. Questo parametro è facoltativo e può essere NULL. Il chiamante deve assicurarsi che l'operazione di I/O rimanga valida per la durata di questa routine e che l'I/O non abbia un set di routine annulla( ad esempio, la funzione FltSetCancelCompletion non deve essere stata chiamata sull'operazione di I/O). Si noti che callbackData deve essere tenuto dal chiamante perché non può essere passato a un driver di livello inferiore.

Valore restituito

FltCancellableWaitForMultipleObjects può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	Il chiamante specificato WaitAll per il parametro WaitType e tutti gli oggetti dispatcher nella matrice ObjectArray sono stati impostati sullo stato segnalato.
STATUS_TIMEOUT	Si è verificato un timeout prima che il set specificato di condizioni di attesa sia stato soddisfatto. Questo valore può essere restituito anche quando non è possibile soddisfare immediatamente il set specificato di condizioni di attesa e Timeout è impostato su zero.
STATUS_WAIT_0 tramite STATUS_WAIT_63	Il chiamante specificato WaitAny for WaitType e uno degli oggetti dispatcher nella matrice ObjectArray è stato impostato sullo stato segnalato. I sei bit inferiori del valore restituito codificano l'indice in base zero dell'oggetto che ha soddisfatto l'attesa.
STATUS_ABANDONED_WAIT_0 tramite STATUS_ABANDONED_WAIT_63	Il chiamante ha tentato di attendere un mutex che è stato abbandonato. I sei bit inferiori del valore restituito codificano l'indice in base zero del mutex nella matrice ObjectArray .
STATUS_CANCELLED	L'attesa è stata interrotta da una richiesta di annullamento in sospeso nell'operazione di I/O. Si noti che questo valore viene restituito solo se CallbackData corrispondente a un'operazione basata su IRP viene passata a FltCancellableWaitForMultipleObjects e l'I/O è stato annullato da una routine come FltCancelIo.
STATUS_THREAD_IS_TERMINATING	L'attesa è stata interrotta perché un'applicazione o l'utente ha terminato il thread.

Il valore restituito indica solo lo stato dell'attesa.

Si noti che la macro NT_SUCCESS restituisce FALSE ("errore") per i valori di stato STATUS_CANCELLED e STATUS_THREAD_IS_TERMINATING e TRUE ("success") per tutti gli altri valori di stato.

Commenti

FltCancellableWaitForMultipleObjects esegue un'operazione di attesa annullabile sugli oggetti dispatcher. Se l'utente o l'applicazione termina il thread o se un'operazione di I/O associata al thread è stata annullata da una routine come FltCancelIo, l'attesa viene annullata.

La routine è progettata per supportare le linee guida per il completamento/annullamento di I/O. L'obiettivo di queste linee guida è consentire agli utenti di terminare rapidamente le applicazioni. Questo, a sua volta, richiede che le applicazioni abbiano la possibilità di terminare rapidamente i thread che eseguono operazioni di I/O e qualsiasi operazione di I/O corrente. Questa routine consente ai thread utente di bloccare (ovvero attendere) nel kernel per il completamento di I/O, oggetti dispatcher o variabili di sincronizzazione in modo da consentire l'annullamento dell'attesa. Questa routine consente inoltre di terminare l'attesa del thread se il thread viene terminato da un utente o da un'applicazione.

Ad esempio, un reindirizzamento potrebbe dover creare una o più operazioni di I/O secondarie per elaborare un I/O in modalità utente e attendere in modo sincrono il completamento delle richieste secondarie. Un modo per eseguire questa operazione consiste nel configurare un evento che verrà segnalato dalla routine di completamento delle operazioni di I/O secondarie e quindi attendere che l'evento venga segnalato. Quindi, per eseguire un'operazione di attesa annullabile, FltCancellableWaitForMultipleObjects viene chiamato passando gli eventi associati alle operazioni di I/O secondarie e l'operazione di I/O in modalità utente originale. L'attesa del thread che l'evento deve essere segnalato viene annullato se si verifica un evento di terminazione in sospeso o se l'operazione di I/O in modalità utente originale viene annullata.

Si noti che l'interruzione dell'attesa non annulla automaticamente qualsiasi operazione di I/O rilasciata dal chiamante, che deve essere gestita separatamente dal chiamante.

Ogni oggetto thread include una matrice predefinita di blocchi di attesa che è possibile usare per attendere contemporaneamente diversi oggetti. Se possibile, è consigliabile usare la matrice predefinita di blocchi di attesa in un'operazione in attesa multipla perché non è necessario allocare e deallocare in un secondo momento l'archiviazione a blocchi di attesa aggiuntivi. Tuttavia, se il numero di oggetti che è necessario attendere contemporaneamente è maggiore del numero di blocchi di attesa predefiniti, usare il parametro WaitBlockArray per specificare un set alternativo di blocchi di attesa da usare nell'operazione di attesa. I driver devono allocare solo un buffer di memoria di grandi dimensioni sufficiente per WaitBlockArray. Non è necessario inizializzare il buffer e i driver possono considerarlo come una struttura opaca. È possibile liberare il buffer una volta restituita la routine.

Se Count è maggiore di MAXIMUM_WAIT_OBJECTS o se WaitBlockArray è NULL e Count è maggiore di THREAD_WAIT_OBJECTS, il bug verifica 0xC di sistema : MAXIMUM_WAIT_OBJECTS_EXCEEDED.

Una considerazione speciale si applica quando uno o più elementi del parametro ObjectArray passati a FltCancellableWaitForMultipleObjects fa riferimento a un mutex. Se l'oggetto dispatcher in attesa è un mutex, il recapito APC è uguale a quello di tutti gli altri oggetti dispatcher durante l'attesa. Tuttavia, una volta che FltCancellableWaitForMultipleObjects restituisce con STATUS_SUCCESS e il thread contiene effettivamente il mutex, vengono recapitate solo API speciali in modalità kernel. Il recapito di tutte le altre API, sia in modalità kernel che in modalità utente, è disabilitato. Questa restrizione sul recapito delle API persiste fino a quando non viene rilasciato il mutex.

Un mutex può essere acquisito in modo ricorsivo solo minlong volte. Se questo limite viene superato, la routine genera un'eccezione STATUS_MUTANT_LIMIT_EXCEEDED.

La routine FltCancellableWaitForMultipleObjects deve essere chiamata in IRQL PASSIVE_LEVEL se il parametro CallbackData rappresenta un'IRP di Gestione filtri valida. In caso contrario, la routine può essere chiamata in IRQL minore o uguale a APC_LEVEL. Le API del kernel normali possono essere disabilitate dal chiamante, se necessario, chiamando le routine KeEnterCriticalRegion o FsRtlEnterFileSystem . Tuttavia, le API kernel speciali non devono essere disabilitate.

FltCancellableWaitForMultipleObjects asserisce nelle build di debug se callbackData rappresenta un'operazione IRP di Filter Manager, ma l'IRP nella struttura CallbackData è NULL.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (include Ntifs.h, Fltkernel.h)
Libreria	Fltmgr.lib
IRQL	Vedere La sezione Osservazioni.