Funzione FltCheckOplockEx (fltkernel.h)

Articolo
08/07/2023

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 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 oplock opaco per il file. Questo puntatore deve essere stato inizializzato da una chiamata precedente a FltInitializeOplock.

[in] CallbackData

Puntatore alla struttura dei dati di callback FLT_CALLBACK_DATAper l'operazione di I/O.

[in] Flags

Maschera di bit per l'operazione di I/O di file associata. Un driver minifiltro imposta i bit per specificare il comportamento di FltCheckOplockEx. Il parametro flag include le opzioni seguenti:

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

Consente a un'interruzione di blocco opportunistica di procedere 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 sul 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 di oplock si verifica; ovvero, 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 IRP_MJ_CREATE richiesta 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 una richiesta di creazione di questo tipo 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 WaitCompletionRoutine e PrePostCallbackDataRoutine puntare. 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 oplock, 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 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.

Si noti che quando viene chiamato il WaitCompleteRoutine , la sottostruttura IoStatus potrebbe essere compilata con uno stato di errore (ad esempio STATUS_CANCELLED). È necessario controllare questo stato e reagire in modo appropriato.

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 inserita 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
FLT_PREOP_COMPLETE	FltCheckOplockEx 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.
FLT_PREOP_PENDING	È stata avviata un'interruzione di oplock, che ha causato la pubblicazione dell'operazione di I/O in una coda di lavoro. L'operazione di I/O è rappresentata dai dati di callback a cui punta il parametro CallbackData.
FLT_PREOP_SUCCESS_WITH_CALLBACK	I dati di callback a cui punta il parametro callbackData non è stata applicata la 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 flag di , un'interruzione di oplock potrebbe essere effettivamente in corso anche se l'operazione di I/O non è stata bloccata. 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 della struttura di dati di IoStatus della struttura dei dati di callback FLT_CALLBACK_DATA.

Osservazioni

Un driver minifiltro 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 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
- IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION

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 di FltCheckOplockEx restituisce.

Per altre informazioni sui blocchi opportunistici, vedere la documentazione di Microsoft Windows SDK.

Fabbisogno

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