Funzione FltCheckOplock (fltkernel.h)

Articolo
02/26/2024

Un driver minifilter chiama FltCheckOplock 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 (oplock) corrente del file.

Sintassi

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplock(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [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 alla struttura dei dati di callback (FLT_CALLBACK_DATA) per l'operazione di I/O.

[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 FltCheckOplock.

[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 FltCheckOplock.

Valore restituito

FltCheckOplock restituisce uno dei codici di FLT_PREOP_CALLBACK_STATUS seguenti:

Codice restituito	Descrizione
FLT_PREOP_COMPLETE	FltCheckOplock ha rilevato un errore di allocazione del pool o una chiamata alla funzione FsRtlCheckOplock ha restituito un errore. FltCheckOplock imposterà 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 questo FLT_CALLBACK_DATA.
FLT_PREOP_PENDING	È 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 .
FLT_PREOP_SUCCESS_WITH_CALLBACK	L'operazione di I/O è stata eseguita immediatamente. Tenere presente che se questa operazione è stata un'operazione di creazione che ha specificato FILE_COMPLETE_IF_OPLOCKED nel parametro create-options, potrebbe verificarsi un'interruzione di blocco in corso anche se l'operazione è stata eseguita immediatamente. Per determinare se si tratta della situazione, il chiamante deve controllare lo stato nel membro Status della struttura IO_STATUS_BLOCK del membro IoStatusdella struttura dei dati di callback FLT_CALLBACK_DATA.

Commenti

Un driver minifilter chiama FltCheckOplock 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, FltCheckOplock restituisce FLT_PREOP_PENDING e chiama la routine di callback a cui punta il parametro PrePostCallbackDataRoutine .

Se un driver minifilter usa oplock, deve chiamare FltCheckOplock 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 FltCheckOplock 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 FltCheckOplock restituisca.

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