Funzione FsRtlCheckOplockEx (ntifs.h)

Articolo
12/21/2024

La routine FsRtlCheckOplockEx sincronizza l'IRP per un'operazione di I/O di file con lo stato di blocco opportunistico corrente del file.

Sintassi

NTSTATUS FsRtlCheckOplockEx(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in, optional] PVOID                         Context,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine
);

Parametri

[in] Oplock

Puntatore di blocco opportunistico opaco per il file. Questo puntatore deve essere stato inizializzato da una chiamata precedente a FsRtlInitializeOplock.

[in] Irp

Puntatore all'IRP per l'operazione di I/O.

[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 FsRtlCheckOplockEx. Il parametro flag include le opzioni seguenti:

Valore	Significato
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Specifica di consentire 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)	Supportato a partire da Windows 7. Specifica che FsRtlCheckOplockEx deve controllare solo la presenza di una chiave di blocco opportunistica sul FILE_OBJECT associato all'IRP a cui punta il parametro Irp . FsRtlCheckOplockEx 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 blocco opportunistica.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Supportato a partire da Windows 7. Specifica che FsRtlCheckOplockEx 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.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Supportato a partire da Windows 7. Specifica di consentire a tutte le interruzioni di blocco opportunistiche di procedere indipendentemente dalla chiave di blocco opportunistica.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Supportato a partire da Windows 8. Specifica che Oplock è associato all'elemento padre (directory) del file o della directory a cui viene indirizzato l'IRP nel parametro Irp.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Supportato a partire da Windows 8. 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 blocco opportunistica.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Supportato a partire da Windows 8. Specifica la gestione di un'interruzione di blocco opportunistica 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.

[in, optional] Context

Puntatore alle informazioni sul contesto definite dal chiamante da passare alle routine di callback a cui puntano i parametri CompletionRoutine e PostIrpRoutine.

[in, optional] CompletionRoutine

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

Questa routine viene dichiarata come segue:

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

Questa routine presenta i parametri seguenti:

Parametro	Descrizione
Contesto	Puntatore alle informazioni di contesto passato nel parametro Context a FsRtlCheckOplockEx.
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 inserita in una coda di lavoro. Questo parametro è facoltativo e può essere NULL.

Questa routine viene dichiarata come segue:

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

Questa routine presenta i parametri seguenti:

Parametro	Descrizione
Contesto	Puntatore alle informazioni di contesto passato nel parametro Context a FsRtlCheckOplockEx.
Irp	Puntatore all'IRP per l'operazione di I/O.

Valore restituito

FsRtlCheckOplockEx 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 di blocco opportunistico (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 opportunistica. 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 blocco opportunistico è stato interrotto.
STATUS_PENDING	È stata avviata un'interruzione di blocco opportunistica e il controllo dell'IRP è stato passato al pacchetto oplock. Se CompletionRoutine è NULL, questa routine verrà bloccata durante l'elaborazione dell'interruzione di oplock anziché restituire STATUS_PENDING. STATUS_PENDING è un codice riuscito.

Osservazioni

FsRtlCheckOplockEx sincronizza l'IRP per un'operazione di I/O con lo stato di blocco opportunistico corrente di un file in base alle condizioni seguenti:

Se l'operazione di I/O causerà l'interruzione del blocco opportunistico, viene avviata l'interruzione di blocco opportunistica.
Se l'operazione di I/O non può continuare finché non viene completata l'interruzione di blocco opportunistica e viene specificata una routine di completamento in CompletionRoutine, FsRtlCheckOplockEx restituisce STATUS_PENDING e chiama la routine di callback specificata in PostIrpRoutine. Quando l'interruzione di blocco opportunistica è 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 blocco opportunistica e non è stata specificata CompletionRoutine, FsRtlCheckOplockEx non restituirà finché non viene riconosciuta l'interruzione di blocco opportunistica.

È necessario specificare un PostIrpRoutine solo se è stato specificato un CompletionRoutine .

Se un file system o un driver di filtro usa blocchi opportunistici, deve chiamare FsRtlCheckOplockEx da qualsiasi routine dispatch per le operazioni di I/O che possono causare interruzioni di blocco opportunistiche. Questa regola si applica ai seguenti tipi di operazioni di I/O, perché queste operazioni possono causare interruzioni di blocco opportunistiche:

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

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

I minifiltri devono chiamare FltCheckOplockEx anziché FsRtlCheckOplockEx.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista
piattaforma di destinazione	Universale
intestazione	ntifs.h (include Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	<= APC_LEVEL