Funzione FsRtlCheckOplockEx (ntifs.h)

Articolo
03/05/2024

La routine FsRtlCheckOplockEx sincronizza l'IRP per un'operazione di I/O di file con lo stato di blocco opportunistico corrente (oplock) 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 del file associata. Un file system o un driver di filtro imposta i bit per specificare il comportamento di FsRtlCheckOplockEx. Il parametro Flags include le opzioni seguenti:

Valore	Significato
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Specifica di consentire a un'interruzione di blocco opportunistica di continuare 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 nel FILE_OBJECT associato all'IRP a cui punta il parametro Irp . FsRtlCheckOplockEx deve quindi aggiungere la chiave se ne viene fornita una nell'IRP. Nessun'altra elaborazione oplock si verifica; vale a dire, 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 . 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 tale richiesta di creazione quando in precedenza non è riuscito.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Supportato a partire da Windows 7. Specifica di consentire l'esecuzione di tutte le interruzioni di blocco opportunistiche 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 aperto originariamente con il flag 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ò comportare 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 completamento 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
Context	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 registrata 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
Context	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	Non è possibile eseguire l'interruzione di blocco opportunistico (oplock). L'IRP è una richiesta di IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK è stato specificato nel parametro delle opzioni di creazione per l'operazione ed è presente un oplock concesso.
STATUS_OPLOCK_BREAK_IN_PROGRESS	È in corso una pausa di blocco opportunistica. L'IRP è una richiesta IRP_MJ_CREATE e FILE_COMPLETE_IF_OPLOCKED è stato specificato nel parametro di creazione delle opzioni per l'operazione. STATUS_OPLOCK_BREAK_IN_PROGRESS è un codice di esito positivo 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.

Commenti

FsRtlCheckOplockEx sincronizza 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 fino al completamento dell'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 completionRoutine non è stato specificato, FsRtlCheckOplockEx non restituirà finché non viene riconosciuta l'interruzione di blocco opportunistica.

È necessario specificare PostIrpRoutine solo se è stata specificata un'istanza di 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 tipi seguenti 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 minifilter devono chiamare FltCheckOplockEx anziché FsRtlCheckOplockEx.

Requisiti

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