Funzione FsRtlCheckOplock (ntifs.h)

Articolo
12/21/2024

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

Sintassi

NTSTATUS FsRtlCheckOplock(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [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, 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 FsRtlCheckOplock.
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 FsRtlCheckOplock.
Irp	Puntatore all'IRP per l'operazione di I/O.

Valore restituito

La routine FsRtlCheckOplock 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	Se l'IRP è un IRP_MJ_CREATE e FILE_OPEN_REQUIRING_OPLOCK si trova in CreateOptions di IRP, la routine non avvierà un'interruzione di un blocco opportunistico esistente, ma ha esito negativo con STATUS_CANNOT_BREAK_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 riuscito.
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

FsRtlCheckOplock 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, FsRtlCheckOplock restituisce STATUS_PENDING e chiama la routine di callback a cui punta il parametro PostIrpRoutine .

Se un file system o un driver di filtro usa blocchi opportunistici, deve chiamare FsRtlCheckOplock da qualsiasi routine dispatch per 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 informazioni dettagliate sui blocchi opportunistici, vedere la documentazione di Windows SDK.

I minifiltri devono chiamare FltCheckOplock anziché FsRtlCheckOplock.

Fabbisogno

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