Funzione FltCancellableWaitForSingleObject (fltkernel.h)

Articolo
02/29/2024

La routine FltCancellableWaitForSingleObject esegue un'operazione di attesa annullabile (un'attesa che può essere terminata) su un oggetto dispatcher.

Sintassi

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

Parametri

[in] Object

Puntatore a un oggetto dispatcher inizializzato (evento, mutex, semaforo, thread o timer) per il quale il chiamante fornisce la risorsa di archiviazione.

[in, optional] Timeout

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

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 per un periodo illimitato fino a quando l'oggetto non viene impostato sullo stato segnalato.

Un valore di timeout positivo specifica un'ora assoluta, rispetto al 1° gennaio 1601. Un valore timeout negativo specifica un intervallo relativo all'ora corrente. Le ore di scadenza assolute tengono traccia delle modifiche apportate all'ora di sistema. Le scadenze relative non sono interessate dalle modifiche all'ora di sistema.

Se si specifica Timeout , l'attesa viene soddisfatta automaticamente se l'oggetto non è impostato sullo stato segnalato alla scadenza dell'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 soddisfatta immediatamente, come nell'acquisizione di un mutex.

[in, optional] CallbackData

Puntatore alla struttura FLT_CALLBACK_DATA che rappresenta l'operazione di I/O rilasciata dall'utente e che può essere annullata dall'utente. 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 di annullamento( ad esempio, una funzione FltSetCancelCompletion non deve essere stata chiamata sull'operazione di I/O). Si noti che il chiamante deve contenere CallbackData; non può essere passato a un driver di livello inferiore.

Valore restituito

FltCancellableWaitForSingleObject può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	L'oggetto dispatcher specificato dal parametro Object è stato impostato sullo stato segnalato.
STATUS_TIMEOUT	Si è verificato un timeout prima che l'oggetto sia stato impostato su uno stato segnalato. Questo valore può essere restituito anche quando la condizione di attesa specificata non può essere soddisfatta immediatamente e Timeout è impostato su zero.
STATUS_ABANDONED_WAIT_0	Il chiamante ha tentato di attendere un mutex abbandonato.
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 corrisponde a un'operazione basata su IRP viene passata a FltCancellableWaitForSingleObject e l'I/O è stato annullato da una routine come FltCancelIo.
STATUS_THREAD_IS_TERMINATING	L'attesa è stata interrotta perché l'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 ("operazione riuscita") per tutti gli altri valori di stato.

Commenti

La routine FltCancellableWaitForSingleObject esegue un'operazione di attesa annullabile su un oggetto dispatcher. Se l'utente o l'applicazione termina il thread o se un I/O associato al thread è stato annullato 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. 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 redirector potrebbe dover creare un'operazione di I/O secondaria per elaborare un I/O in modalità utente e attendere in modo sincrono il completamento della richiesta secondaria. Un modo per eseguire questa operazione consiste nel configurare un evento che verrà segnalato dalla routine di completamento dell'operazione di I/O secondaria e quindi attendere che l'evento venga segnalato. Quindi, per eseguire un'operazione di attesa annullabile, FltCancellableWaitForSingleObject viene chiamato passaggio dell'evento associato all'operazione di I/O secondaria e l'operazione di I/O in modalità utente originale. L'attesa del thread per la segnalazione dell'evento viene annullata 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 alcuna operazione di I/O rilasciata dal chiamante, che deve essere gestita separatamente dal chiamante.

Una considerazione speciale si applica quando il parametro Object passato a FltCancellableWaitForSingleObject è un mutex. Se l'oggetto dispatcher in attesa è un mutex, il recapito APC corrisponde a quello di tutti gli altri oggetti dispatcher durante l'attesa. Tuttavia, dopo che Flt DisabilitableWaitForSingleObject restituisce con STATUS_SUCCESS e il thread contiene effettivamente il mutex, vengono recapitate solo API speciali in modalità kernel. Il recapito di tutti gli altri APN, sia in modalità kernel che in modalità utente, è disabilitato. Questa restrizione per il recapito delle API persiste fino al rilascio del mutex.

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

Flt DisabilitableWaitForSingleObject deve essere chiamato in IRQL PASSIVE_LEVEL se il parametro CallbackData rappresenta un IRP di gestione filtri valido. 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 speciali del kernel non devono essere disabilitate.

La routine FltCancellableWaitForSingleObject verrà asserita nelle compilazioni di debug se CallbackData rappresenta un'operazione IRP di Gestione filtri, ma l'IRP nella struttura CallbackData è NULL.

Requisiti

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