Funzione FsRtlCheckOplockEx2 (ntifs.h)

Articolo
12/20/2024

FsRtlCheckOplockEx2 sincronizza l'IRP per un'operazione di I/O di file con lo stato di blocco opportunistico corrente 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 di file associata. Un file system o un driver di filtro imposta i bit per specificare il comportamento di FsRtlCheckOplockEx2. Flag sono disponibili le opzioni seguenti:

Valore flag	Significato
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Specifica di consentire a un'interruzione di oplock 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 FsRtlCheckOplockEx2 deve controllare solo la presenza di una chiave oplock nel FILE_OBJECT associato all'IRP a cui punta il parametro Irp . FsRtlCheckOplockEx2 deve quindi aggiungere la chiave se ne viene fornita una in 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 . il FsRtlOplockFsctrl viene chiamato durante l'elaborazione di una richiesta di IRP_MJ_CREATE che 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. Supportato a partire da Windows 7.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Specifica di consentire l'esecuzione di tutte le interruzioni di oplock indipendentemente dalla chiave 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 indirizzato 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 FILE_DELETE_ON_CLOSE impostato nelle relative opzioni di creazione. Questo flag non ha effetto se Irp non è un'operazione di IRP_MJ_CLEANUP. Se si specifica questo flag, potrebbe verificarsi 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 quando si elimina 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

Riservato; deve essere impostato su zero.

[in, optional] CompletionRoutineContext

Puntatore alle informazioni sul 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 è in corso un'interruzione di oplock, questa routine viene chiamata al completamento 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 oplock.

il CompletionRoutine viene dichiarato come segue:

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

CompletionRoutine presenta i parametri seguenti:

Context: 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 registrata in 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 presenta i parametri seguenti:

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

[in] Timeout

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

[in, optional] NotifyContext

Puntatore a una struttura OPLOCK_NOTIFY_PARAMS a cui passare la 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 presenta i parametri seguenti:

NotifyParams, impostato 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 oplock. L'IRP è una richiesta di IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK è stato specificato nel parametro create options per l'operazione e viene concesso un oplock.
STATUS_OPLOCK_BREAK_IN_PROGRESS	È in corso un'interruzione di blocco. L'IRP è una richiesta di IRP_MJ_CREATE e FILE_COMPLETE_IF_OPLOCKED è stato specificato nel parametro create options per l'operazione. STATUS_OPLOCK_BREAK_IN_PROGRESS è un codice di operazione riuscita restituito se è stato impostato OPLOCK_FLAG_COMPLETE_IF_OPLOCKED e un oplock è stato interrotto.
STATUS_PENDING	È in corso un'interruzione di oplock e il controllo dell'IRP è stato passato al pacchetto oplock. Se CompletionRoutine è NULL, FsRtlCheckOplockEx2 blocchi mentre l'interruzione oplock viene elaborata anziché restituire STATUS_PENDING. STATUS_PENDING è un codice riuscito.

Osservazioni

I minifiltri 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 dell'oplock, viene avviata l'interruzione oplock.
Se l'operazione di I/O non può continuare finché non viene completata l'interruzione di oplock e viene specificata una routine di completamento in Completamento, 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 CompletionRoutine.
Se l'operazione di I/O non può continuare fino al completamento dell'interruzione di oplock e non è stato specificato il CompletionRoutine, 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, verrà chiamato NotifyRoutine 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 CompletionRoutine è NULL ed è necessario bloccare il thread del chiamante per attendere il completamento dell'interruzione.

Se la NotifyRoutine viene richiamata per motivi OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT, verrà sempre richiamata per motivo OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED se l'attesa termina/termina 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.

È necessario specificare un PostIrpRoutine solo se è stato specificato un 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 Flag, FsRtlCheckOplockEx2 interromperà in modo incondizionato qualsiasi oplock padre esistente; ovvero, il codice principale nel Irp non viene considerato.

Se un file system usa oplock, deve chiamare FsRtlCheckOplockEx2 da qualsiasi routine dispatch per 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: