Funzione FsRtlCheckOplockEx2 (ntifs.h)

Articolo
02/26/2024

FsRtlCheckOplockEx2 sincronizza l'IRP per un'operazione di I/O file con lo stato di blocco opportunistico corrente (oplock) del file.

Sintassi

NTSTATUS FsRtlCheckOplockEx2(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in]           ULONG                         FlagsEx2,
  [in, optional] PVOID                         CompletionRoutineContext,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine,
  [in]           ULONGLONG                     Timeout,
  [in, optional] PVOID                         NotifyContext,
  [in, optional] POPLOCK_NOTIFY_ROUTINE        NotifyRoutine
);

Parametri

[in] Oplock

Puntatore alla struttura oplock opaca per il file. Questo puntatore deve essere stato inizializzato da una chiamata precedente a FsRtlInitializeOplock.

[in] Irp

Puntatore all'IRP che dichiara l'operazione di I/O richiesta.

[in] Flags

Maschera di bit per l'operazione di I/O del file associato. Un file system o un driver di filtro imposta bit per specificare il comportamento di FsRtlCheckOplockEx2. I flag hanno le opzioni seguenti:

Valore flag	Significato
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Specifica per consentire a un'interruzione di oplock di procedere senza bloccare o in sospeso l'operazione che ha causato l'interruzione del blocco.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Specifica che FsRtlCheckOplockEx2 deve verificare solo la presenza di una chiave di oplock nella FILE_OBJECT associata all'IRP a cui punta il parametro Irp. FsRtlCheckOplockEx2 deve quindi aggiungere la chiave se viene fornita nell'IRP. Nessun'altra elaborazione di oplock si verifica; ovvero, non si verificherà alcuna interruzione di oplock. Supportato a partire da Windows 7.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Specifica che FsRtlCheckOplockEx2 deve ripristinare qualsiasi stato configurato in precedenza tramite una chiamata alla routine FsRtlOplockFsctrl . FsRtlOplockFsctrl viene chiamato durante l'elaborazione di una richiesta di IRP_MJ_CREATE che specifica il flag di FILE_OPEN_REQUIRING_OPLOCK nel parametro delle opzioni di creazione. Il flag OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK viene in genere usato nell'elaborazione finale di una richiesta di creazione in precedenza non riuscita. Supportato a partire da Windows 7.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Specifica per consentire a tutte le interruzioni di oplock di procedere indipendentemente dalla chiave di oplock. Supportato a partire da Windows 7.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Specifica che Oplock è associato all'elemento padre (directory) del file o della directory a cui viene indirizzata l'IRP nel parametro Irp . Supportato a partire da Windows 8.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Specifica che l'operazione di I/O specificata in Irp è un IRP_MJ_CLEANUP per un handle originariamente aperto con il flag di FILE_DELETE_ON_CLOSE impostato nelle opzioni di creazione. Questo flag non ha alcun effetto se Irp non è un'operazione di IRP_MJ_CLEANUP. La specifica di questo flag può causare un'interruzione di oplock. Supportato a partire da Windows 8.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Specifica la gestione di un'interruzione di oplock in una directory padre durante l'eliminazione di un file o un collegamento in tale directory. Se specificato, questo flag deve essere combinato con OPLOCK_FLAG_PARENT_OBJECT. Questo flag deve essere specificato quando il file system elabora un'operazione che comporta la rimozione di un collegamento o di un file. Supportato a partire da Windows 8.

[in] FlagsEx2

Riservati; deve essere impostato su zero.

[in, optional] CompletionRoutineContext

Puntatore a informazioni di contesto definite dal chiamante da passare alla routine di callback a cui punta il parametro CompletionRoutine . Questo parametro è facoltativo e può essere NULL.

[in, optional] CompletionRoutine

Puntatore a una routine di callback fornita dal chiamante. Se un'interruzione di oplock è in corso, questa routine viene chiamata al termine dell'interruzione. Questo parametro è facoltativo e può essere NULL. Se è NULL, FsRtlCheckOpLockEx2 opera in modo sincrono, inserendo il chiamante in uno stato di attesa fino al completamento dell'interruzione di oplock.

CompletamentoRoutine viene dichiarato come indicato di seguito:

typedef VOID
(*POPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PVOID Context,
      IN PIRP Irp
      );

CompletamentoRoutine include i parametri seguenti:

Contesto: puntatore alle informazioni di contesto passato nel parametro Context a FsRtlCheckOplockEx2.
Irp: puntatore all'IRP per l'operazione di I/O.

[in, optional] PostIrpRoutine

Puntatore a una routine di callback fornita dal chiamante da chiamare se l'operazione di I/O viene inviata a una coda di lavoro. Questo parametro è facoltativo e può essere NULL.

PostIrpRoutine viene dichiarato come segue:

typedef VOID
(*POPLOCK_FS_PREPOST_IRP) (
      IN PVOID Context,
      IN PIRP Irp
      );

PostIrpRoutine include i parametri seguenti:

Contesto, ovvero un puntatore informazioni di contesto passato nel parametro Context a FsRtlCheckOplockEx2.
Irp: puntatore all'IRP per l'operazione di I/O.

[in] Timeout

Se non zero, specifica un timeout (in millisecondi) per attendere un evento usato per bloccare il thread del chiamante per attendere il completamento dell'interruzione di oplock. Questo valore viene ignorato a meno che non siano valide entrambe le condizioni seguenti: CompletamentoRoutine è NULL e NotifyRoutine non è NULL.

[in, optional] NotifyContext

Puntatore a una struttura OPLOCK_NOTIFY_PARAMS da passare alla routine di callback a cui punta il parametro NotifyRoutine . Questo parametro è facoltativo e può essere NULL.

[in, optional] NotifyRoutine

Puntatore a una routine di callback fornita dal chiamante da chiamare per la notifica dello stato di oplock. Questo parametro è facoltativo e può essere NULL.

NotifyRoutine viene dichiarato come segue:

typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
      IN POPLOCK_NOTIFY_PARAMS NotifyParams
      );

NotifyRoutine include i parametri seguenti:

NotifyParams, impostato su come parametro NotifyContext passato a FsRtlCheckOplockEx2.

Valore restituito

FsRtlCheckOplockEx2 restituisce STATUS_SUCCESS o un codice NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_CANCELLED	L'IRP è stato annullato. STATUS_CANCELLED è un codice di errore.
STATUS_CANNOT_BREAK_OPLOCK	Impossibile eseguire l'interruzione del blocco. L'IRP è una richiesta di IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK è stato specificato nel parametro delle opzioni di creazione per l'operazione e viene concesso un oplock concesso.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Un'interruzione di oplock è in corso. L'IRP è una richiesta di IRP_MJ_CREATE e FILE_COMPLETE_IF_OPLOCKED è stato specificato nel parametro delle opzioni di creazione per l'operazione. STATUS_OPLOCK_BREAK_IN_PROGRESS è un codice di esito positivo restituito se è stato impostato OPLOCK_FLAG_COMPLETE_IF_OPLOCKED e un oplock è stato interrotto.
STATUS_PENDING	Un'interruzione di oplock è in corso e il controllo dell'IRP è stato passato al pacchetto di oplock. Se CompletamentoRoutine è NULL, FsRtlCheckOplockEx2 blocca mentre l'interruzione di oplock viene elaborata anziché restituire STATUS_PENDING. STATUS_PENDING è un codice riuscito.

Commenti

I minifilter devono chiamare FltCheckOplockEx anziché FsRtlCheckOplockEx2.

FsRtlCheckOplockEx2 sincronizza L'IRP per un'operazione di I/O con lo stato di oplock corrente di un file in base alle condizioni seguenti:

Se l'operazione di I/O causerà l'interruzione del blocco, viene avviata l'interruzione di oplock.
Se l'operazione di I/O non può continuare fino al completamento dell'interruzione di oplock e una routine di completamento in CompletamentoRoutine è stata specificata, FsRtlCheckOplockEx2 restituisce STATUS_PENDING e chiama la routine di callback specificata in PostIrpRoutine. Quando l'interruzione di oplock è stata riconosciuta, viene chiamata la routine di callback in CompletamentoRoutine .
Se l'operazione di I/O non può continuare finché l'interruzione di oplock non è stata completata e il thread del chiamante non è stato specificato, il thread del chiamante viene bloccato e FsRtlCheckOplockEx2 restituirà solo al termine dell'interruzione di oplock.

Se il thread del chiamante è bloccato e NotifyRoutine non è NULL, NotifyRoutine verrà chiamato per uno o tutti i motivi seguenti impostati in NotifyParams:

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

La chiamata a NotifyRoutine per uno dei motivi precedenti si verifica solo se CompletamentoRoutine è NULL ed è necessario bloccare il thread del chiamante per attendere il completamento dell'interruzione.

Se NotifyRoutine viene richiamato per motivo OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT, verrà sempre richiamato per motivo OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED se l'attesa termina/completa per qualsiasi motivo (che potrebbe non essere mai).

FsRtlCheckOplockEx2 ignora i codici di stato OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT e OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED restituiti da NotifyRoutine.

Un postIrpRoutine deve essere specificato solo se è stato specificato un oggetto CompletionRoutine . Quando PostIrpRoutine non è NULL, viene chiamato prima che tutto venga accodato alla coda Irp in attesa.

Se il flag OPLOCK_FLAG_PARENT_OBJECT viene specificato in Flags, FsRtlCheckOplockEx2 interromperà in modo incondizionato qualsiasi oplock padre esistente; ovvero, il codice principale nell'Irp non viene considerato.

Se un file system usa oplock, deve chiamare FsRtlCheckOplockEx2 da qualsiasi routine di invio per operazioni di I/O che possono causare interruzioni di oplock. Questa regola si applica ai tipi seguenti di operazioni di I/O, perché queste operazioni possono causare interruzioni di oplock: