Funzione FsRtlPacchettibleWaitForMultipleObjects (ntifs.h)
La routine FsRtlCancellableWaitForMultipleObjects esegue un'operazione di attesa annullabile (un'attesa che può essere terminata) su uno o più oggetti dispatcher.
Sintassi
NTSTATUS FsRtlCancellableWaitForMultipleObjects(
[in] ULONG Count,
[in] PVOID [] ObjectArray,
[in] WAIT_TYPE WaitType,
[in, optional] PLARGE_INTEGER Timeout,
[in, optional] PKWAIT_BLOCK WaitBlockArray,
[in, optional] PIRP Irp
);
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
Entrambi WaitAll, che indica che tutti gli oggetti specificati devono ottenere uno stato segnalato prima che l'attesa venga soddisfatta; 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 unità di 100 nanosecondi, in cui 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 indefinito fino a quando uno o tutti gli oggetti dispatcher vengono impostati sullo stato segnalato.
Un valore positivo specifica un'ora assoluta, 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 verrà soddisfatta automaticamente se nessuna delle condizioni di attesa specificate viene soddisfatta 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] 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 mantenere i record durante l'esecuzione dell'operazione di attesa.
[in, optional] Irp
Puntatore all'IRP originale che corrisponde all'operazione di I/O rilasciata dall'utente e che può essere annullata dall'utente. Il chiamante deve assicurarsi che l'IRP rimanga valido per la durata di questa routine e che l'IRP non debba avere un set di routine di annullamento( ad esempio, IoSetCancelRoutine non deve essere stato chiamato su IRP). Si noti che l'IRP deve essere mantenuto dal chiamante, non può essere passato a un driver di livello inferiore.
Valore restituito
FsRtlPacchettibleWaitForMultipleObjects può restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
| STATUS_SUCCESS | Il chiamante specificato |
| STATUS_TIMEOUT | Si è verificato un timeout prima che sia stato soddisfatto il set specificato di condizioni di attesa. Questo valore può essere restituito 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 per 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 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'IRP specificato. Si noti che questo valore viene restituito solo se un IRP valido viene passato a FsRtlPacchettibleWaitForMultipleObjects e l'IRP è stato annullato da CancelSynchronousIo. |
| STATUS_THREAD_IS_TERMINATING | L'attesa è stata interrotta perché il thread è stato terminato da un'applicazione o dall'utente. |
Il valore restituito indica solo lo stato dell'attesa. Se applicabile, lo stato effettivo della richiesta di I/O deve essere ottenuto direttamente da un altro IRP generato nel processo di gestione dell'IRP in modalità utente originale.
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.
Osservazioni
La routine FsRtlPacchettibleWaitForMultipleObjects esegue un'operazione di attesa annullabile sugli oggetti dispatcher. Se il thread viene terminato dall'utente o dall'applicazione o se CancelSynchronousIo pubblica una richiesta di annullamento in un IRP (IRP sincrono) threaded associato al thread, l'attesa viene annullata.
La routine fsRtlPacchettibleWaitForMultipleObjects
Ad esempio, un redirector potrebbe dover creare uno o più runtime di integrazione secondari per elaborare un IRP in modalità utente e attendere in modo sincrono il completamento dei runtime di integrazione secondari.For example, a redirector may need to create one or more secondary IRPs to process a user-mode IRP and synchronously wait for the secondary IRPs to complete. Un modo per eseguire questa operazione consiste nel configurare un evento che verrà segnalato dalla routine di completamento dell'IRP secondario e quindi attendere che l'evento venga segnalato. Quindi, per eseguire un'operazione di attesa annullabile, FsRtlPacchettibleWaitForMultipleObjects viene chiamato passando l'evento associato all'IRP secondario, nonché l'IRP 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'IRP in modalità utente originale viene annullato.
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 ha una matrice predefinita di blocchi di attesa che possono essere usati per attendere diversi oggetti contemporaneamente. Quando possibile, la matrice predefinita di blocchi di attesa deve essere usata in un'operazione di attesa multipla perché non è necessario allocare e deallocare in un secondo momento l'archiviazione dei blocchi di attesa aggiuntiva. Tuttavia, se il numero di oggetti da attendere contemporaneamente è maggiore del numero di blocchi di attesa predefiniti, utilizzare il parametro WaitBlockArray per specificare un set alternativo di blocchi di attesa da utilizzare nell'operazione di attesa. I driver devono allocare solo un buffer di memoria sufficientemente grande per WaitBlockArray. Il buffer non deve essere inizializzato e i driver possono considerarlo come una struttura opaca. Il buffer può essere liberato una volta restituita la routine.
Se Count è maggiore di MAXIMUM_WAIT_OBJECTS o se WaitBlockArray è NULL e Count è maggiore di THREAD_WAIT_OBJECTS, il sistema genera controllo bug 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.
Una considerazione speciale si applica quando il parametro ObjectArray passato a FsRtl GestiscibleWaitForMultipleObjects è 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 FsRtlPacchettibleWaitForMultipleObjects restituisce con STATUS_SUCCESS e il thread contiene effettivamente il mutex, vengono recapitati solo API speciali in modalità kernel. Il recapito di tutte le altre API, 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.
è necessario chiamare FsRtlCancellableWaitForMultipleObjects in IRQL PASSIVE_LEVEL se il parametro facoltativo Irp punta a un IRP valido. Se il parametro Irp non viene usato, 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 del kernel speciali non devono essere disabilitate.
FsRtlPacchettibleWaitForMultipleObjects asserirà nelle build di debug se IRQL è maggiore o uguale a APC_LEVEL e il parametro Irp punta a un IRP valido.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows Vista |
| piattaforma di destinazione | Universale |
| intestazione |
ntifs.h (include Ntifs.h) |
| libreria |
NtosKrnl.lib |
| dll | NtosKrnl.exe |
| IRQL | Vedere la sezione Osservazioni. |
| regole di conformità DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm), SpNoWait(storport) |