Funzione FltCheckOplockEx (fltkernel.h)
Un driver minifilter chiama la routine FltCheckOplockEx per sincronizzare la struttura dei dati di callback per un'operazione di I/O di file basata su IRP con lo stato di blocco opportunistico corrente (oplock) del file.
Sintassi
FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplockEx(
[in] POPLOCK Oplock,
[in] PFLT_CALLBACK_DATA CallbackData,
[in] ULONG Flags,
[in, optional] PVOID Context,
[in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE WaitCompletionRoutine,
[in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);
Parametri
[in] Oplock
Puntatore a oplock opaco per il file. Questo puntatore deve essere stato inizializzato da una chiamata precedente a FltInitializeOplock.
[in] CallbackData
Puntatore ai dati di callback FLT_CALLBACK_DATAstruttura per l'operazione di I/O.
[in] Flags
Maschera di bit per l'operazione di I/O del file associata. Un driver minifilter imposta i bit per specificare il comportamento di FltCheckOplockEx. Il parametro Flags include le opzioni seguenti:
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)
Consente a un'interruzione di blocco opportunistica di continuare senza bloccare o in sospeso l'operazione che ha causato l'interruzione di oplock.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)
Specifica che FltCheckOplockEx deve controllare solo la presenza di una chiave di blocco opportunistica nel FILE_OBJECT associato all'operazione di I/O. Queste operazioni di I/O sono rappresentate dai dati di callback a cui punta il parametro CallbackData . FltCheckOplockEx deve quindi aggiungere la chiave se ne viene fornita una nell'operazione di I/O. Nessun'altra elaborazione oplock si verifica; vale a dire, non si verificherà alcuna interruzione di blocco opportunistica.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)
Specifica che FsRtlCheckOplockEx deve ripristinare qualsiasi stato configurato in precedenza tramite una chiamata alla routine FltOplockFsctrl . FltOplockFsctrl viene chiamato quando viene elaborata una richiesta di IRP_MJ_CREATE. Questa richiesta IRP_MJ_CREATE specifica il flag FILE_OPEN_REQUIRING_OPLOCK nel parametro create options. Il flag OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK viene in genere usato nell'elaborazione finale di tale richiesta di creazione quando in precedenza non è riuscito.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)
Consente a tutte le interruzioni di blocco opportunistiche di procedere indipendentemente dalla chiave di blocco opportunistica.
[in, optional] Context
Puntatore alle informazioni sul contesto definite dal chiamante da passare alle routine di callback a cui punta WaitCompletionRoutine e PrePostCallbackDataRoutine . Gestione filtri considera queste informazioni come opache.
[in, optional] WaitCompletionRoutine
Puntatore a una routine di callback fornita dal chiamante. Se è in corso un'interruzione di blocco, Gestione filtri chiama questa routine al termine dell'interruzione di oplock. Questo parametro è facoltativo e può essere NULL. Se è NULL, il chiamante viene inserito in uno stato di attesa fino al completamento dell'interruzione di oplock.
Questa routine viene dichiarata come segue:
typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
IN PFLT_CALLBACK_DATA CallbackData,
IN PVOID Context
);
Questa routine presenta i parametri seguenti:
CallbackData
Puntatore alla struttura dei dati di callback per l'operazione di I/O.
Contesto
Puntatore alle informazioni di contesto passato nel parametro Context a FltCheckOplockEx.
[in, optional] PrePostCallbackDataRoutine
Puntatore a una routine di callback fornita dal chiamante da chiamare se l'operazione di I/O viene registrata in una coda di lavoro. Questo parametro è facoltativo e può essere NULL.
Questa routine viene dichiarata come segue:
typedef VOID
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
IN PFLT_CALLBACK_DATA CallbackData,
IN PVOID Context
);
CallbackData
Puntatore alla struttura dei dati di callback per l'operazione di I/O.
Contesto
Puntatore alle informazioni di contesto passato nel parametro Context a FltCheckOplockEx.
Valore restituito
FltCheckOplockEx restituisce uno dei codici di FLT_PREOP_CALLBACK_STATUS seguenti:
| Codice restituito | Descrizione |
|---|---|
|
FltCheckOplockEx ha rilevato un errore di allocazione del pool o una chiamata alla funzione FsRtlCheckOplockEx ha restituito un errore. FltCheckOplockEx imposta il codice di errore nel membro Status della struttura IO_STATUS_BLOCK del membro IoStatus della struttura dei dati di callback FLT_CALLBACK_DATA . Il parametro CallbackData punta a questa struttura FLT_CALLBACK_DATA. |
|
È stata avviata un'interruzione di blocco, che ha causato la pubblicazione dell'operazione di I/O in una coda di lavoro da parte di Gestione filtri. L'operazione di I/O è rappresentata dai dati di callback a cui punta il parametro CallbackData . |
|
I dati di callback a cui punta il parametro CallbackData non sono stati eseguiti tramite penna e l'operazione di I/O è stata eseguita immediatamente. Tenere presente che se il chiamante ha specificato OPLOCK_FLAG_COMPLETE_IF_OPLOCKED nel parametro Flags , un'interruzione di oplock potrebbe essere effettivamente in corso anche se l'operazione di I/O non è stata usata come penna. Per determinare se si tratta della situazione, il chiamante deve verificare la presenza di STATUS_OPLOCK_BREAK_IN_PROGRESS nel membro Status della struttura IO_STATUS_BLOCK del membro IoStatus della struttura dei dati di callback FLT_CALLBACK_DATA . |
Commenti
Un driver minifilter chiama FltCheckOplockEx per sincronizzare un'operazione di I/O basata su IRP con lo stato di oplock corrente di un file in base alle condizioni seguenti:
Se l'operazione di I/O causerà l'interruzione dell'oplock, viene avviata l'interruzione di oplock.
Se l'operazione di I/O non può continuare fino al completamento dell'interruzione oplock, FltCheckOplockEx restituisce FLT_PREOP_PENDING e chiama la routine di callback a cui punta il parametro PrePostCallbackDataRoutine .
Se un driver minifilter usa oplock, deve chiamare FltCheckOplockEx da qualsiasi routine di callback di preoperazione (PFLT_PRE_OPERATION_CALLBACK) per le operazioni di I/O che possono causare interruzioni di oplock. Questa regola si applica ai tipi di operazioni di I/O seguenti, perché queste operazioni possono causare interruzioni di oplock:
IRP_MJ_CLEANUP
IRP_MJ_CREATE
IRP_MJ_FILE_SYSTEM_CONTROL
IRP_MJ_FLUSH_BUFFERS
IRP_MJ_LOCK_CONTROL
IRP_MJ_READ
IRP_MJ_SET_INFORMATION
IRP_MJ_WRITE
L'operazione di I/O deve essere un'operazione di I/O basata su IRP. Per determinare se una determinata struttura di dati di callback rappresenta un'operazione di I/O basata su IRP, utilizzare la macro FLT_IS_IRP_OPERATION .
I minifiltri non devono chiamare di nuovo FltCheckOplockEx all'interno del callback specificato in WaitCompletionRoutine. In questo modo può verificarsi una condizione di deadlock se il pacchetto oplock chiama il callback di completamento prima che FltCheckOplockEx restituisca.
Per altre informazioni sui blocchi opportunistici, vedere la documentazione di Microsoft Windows SDK.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | La routine FltCheckOplockEx è disponibile a partire da Windows 7. |
| Piattaforma di destinazione | Universale |
| Intestazione | fltkernel.h (include Fltkernel.h) |
| Libreria | FltMgr.lib |
| IRQL | <= APC_LEVEL |