Fonction FsRtlCheckOplockEx2 (ntifs.h)

Article
02/26/2024

FsRtlCheckOplockEx2 synchronise l’IRP pour une opération d’E/S de fichier avec l’état actuel de verrouillage opportuniste (oplock) du fichier.

Syntaxe

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
);

Paramètres

[in] Oplock

Pointeur vers la structure oplock opaque pour le fichier. Ce pointeur doit avoir été initialisé par un appel précédent à FsRtlInitializeOplock.

[in] Irp

Pointeur vers l’IRP qui déclare l’opération d’E/S demandée.

[in] Flags

Masque de bits pour l’opération d’E/S de fichier associée. Un système de fichiers ou un pilote de filtre définit des bits pour spécifier le comportement de FsRtlCheckOplockEx2. Les indicateurs ont les options suivantes :

Valeur de l’indicateur	Signification
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Spécifie pour autoriser un arrêt de blocage d’opération à se poursuivre sans bloquer ou en attente de l’opération qui a provoqué l’arrêt de l’oplock.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Spécifie que FsRtlCheckOplockEx2 doit uniquement case activée pour une clé oplock sur le FILE_OBJECT associé à l’IRP vers lequel pointe le paramètre Irp. FsRtlCheckOplockEx2 doit ensuite ajouter la clé si une clé est fournie dans l’IRP. Aucun autre traitement oplock ne se produit ; c’est-à-dire qu’aucun blocage d’opération ne se produira. Pris en charge à partir de Windows 7.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Spécifie que FsRtlCheckOplockEx2 doit rétablir tout état précédemment configuré via un appel à la routine FsRtlOplockFsctrl . FsRtlOplockFsctrl est appelé pendant le traitement d’une demande de IRP_MJ_CREATE qui spécifie l’indicateur FILE_OPEN_REQUIRING_OPLOCK dans le paramètre create options. L’indicateur OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK est généralement utilisé dans le traitement final d’une telle demande de création lorsqu’elle a échoué précédemment. Pris en charge à partir de Windows 7.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Spécifie d’autoriser tous les sauts de verrouillage d’opération à se poursuivre, quelle que soit la clé oplock. Pris en charge à partir de Windows 7.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Spécifie que Oplock est associé au parent (répertoire) du fichier ou du répertoire vers lequel l’IRP dans le paramètre Irp est dirigé. Pris en charge à partir de Windows 8.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Spécifie que l’opération d’E/S spécifiée dans Irp est un IRP_MJ_CLEANUP pour un handle qui a été ouvert à l’origine avec l’indicateur FILE_DELETE_ON_CLOSE défini dans ses options de création. Cet indicateur est sans effet si Irp n’est pas une opération IRP_MJ_CLEANUP. La spécification de cet indicateur peut entraîner un blocage d’opération. Pris en charge à partir de Windows 8.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Spécifie la gestion d’un blocage d’opération sur un répertoire parent lors de la suppression d’un fichier ou d’un lien dans ce répertoire. S’il est spécifié, cet indicateur doit être combiné avec OPLOCK_FLAG_PARENT_OBJECT. Cet indicateur doit être spécifié lorsque le système de fichiers traite une opération qui entraîne la suppression d’un lien ou d’un fichier. Pris en charge à partir de Windows 8.

[in] FlagsEx2

Réservés au; doit être défini sur zéro.

[in, optional] CompletionRoutineContext

Pointeur vers les informations de contexte définies par l’appelant à passer à la routine de rappel vers laquelle pointe le paramètre CompletionRoutine . Ce paramètre est facultatif et peut être NULL.

[in, optional] CompletionRoutine

Pointeur vers une routine de rappel fournie par l’appelant. Si un arrêt de blocage d’opération est en cours, cette routine est appelée lorsque l’arrêt est terminé. Ce paramètre est facultatif et peut être NULL. S’il a la valeur NULL, FsRtlCheckOpLockEx2 fonctionne de manière synchrone, plaçant l’appelant dans un état d’attente jusqu’à ce que l’arrêt du blocage d’opération soit terminé.

CompletionRoutine est déclaré comme suit :

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

CompletionRoutine a les paramètres suivants :

Contexte : pointeur d’informations de contexte qui a été passé dans le paramètre Context à FsRtlCheckOplockEx2.
Irp : pointeur vers l’IRP pour l’opération d’E/S.

[in, optional] PostIrpRoutine

Pointeur vers une routine de rappel fournie par l’appelant à appeler si l’opération d’E/S est publiée dans une file d’attente de travail. Ce paramètre est facultatif et peut être NULL.

PostIrpRoutine est déclaré comme suit :

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

PostIrpRoutine a les paramètres suivants :

Context, qui est un pointeur d’informations de contexte qui a été passé dans le paramètre Context à FsRtlCheckOplockEx2.
Irp : pointeur vers l’IRP pour l’opération d’E/S.

[in] Timeout

Si ce n’est pas zéro, spécifie un délai d’attente (en millisecondes) sur un événement utilisé pour bloquer le thread de l’appelant afin d’attendre la fin de l’arrêt du verrouillage d’opération. Cette valeur est ignorée, sauf si les deux conditions suivantes sont remplies : CompletionRoutine a la valeur NULL et NotifyRoutine n’est pas NULL.

[in, optional] NotifyContext

Pointeur vers une structure OPLOCK_NOTIFY_PARAMS à passer à la routine de rappel vers laquelle pointe le paramètre NotifyRoutine . Ce paramètre est facultatif et peut être NULL.

[in, optional] NotifyRoutine

Pointeur vers une routine de rappel fournie par l’appelant à appeler pour la notification d’état oplock. Ce paramètre est facultatif et peut être NULL.

NotifyRoutine est déclaré comme suit :

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

NotifyRoutine a les paramètres suivants :

NotifyParams, qui est défini pour être le paramètre NotifyContext passé à FsRtlCheckOplockEx2.

Valeur retournée

FsRtlCheckOplockEx2 retourne STATUS_SUCCESS ou un code NTSTATUS approprié tel que l’un des éléments suivants :

Code de retour	Description
STATUS_CANCELLED	L’IRP a été annulé. STATUS_CANCELLED est un code d’erreur.
STATUS_CANNOT_BREAK_OPLOCK	Impossible d’effectuer l’arrêt du blocage d’opération. L’IRP est une demande IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK a été spécifié dans le paramètre create options pour l’opération, et un oplock est accordé.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Un blocage d’opération est en cours. L’IRP est une requête IRP_MJ_CREATE et FILE_COMPLETE_IF_OPLOCKED a été spécifié dans le paramètre create options pour l’opération. STATUS_OPLOCK_BREAK_IN_PROGRESS est un code de réussite qui est retourné si OPLOCK_FLAG_COMPLETE_IF_OPLOCKED a été défini et qu’un blocage d’opération a été rompu.
STATUS_PENDING	Un blocage d’opération est en cours et le contrôle de l’IRP a été passé au package oplock. Si CompletionRoutine a la valeur NULL, FsRtlCheckOplockEx2 se bloque pendant le traitement de l’arrêt du blocage d’opération au lieu de retourner STATUS_PENDING. STATUS_PENDING est un code de réussite.

Remarques

Les minifiltres doivent appeler FltCheckOplockEx au lieu de FsRtlCheckOplockEx2.

FsRtlCheckOplockEx2 synchronise l’IRP pour une opération d’E/S avec l’état de verrouillage d’opération actuel d’un fichier selon les conditions suivantes :

Si l’opération d’E/S provoque l’arrêt de l’oplock, l’arrêt d’opération est lancé.
Si l’opération d’E/S ne peut pas continuer tant que l’arrêt du verrouillage d’opération n’est pas terminé et qu’une routine d’achèvement dans CompletionRoutine a été spécifiée, FsRtlCheckOplockEx2 retourne STATUS_PENDING et appelle la routine de rappel spécifiée dans PostIrpRoutine. Une fois l’arrêt du blocage d’opération reconnu, la routine de rappel dans CompletionRoutine est appelée.
Si l’opération d’E/S ne peut pas continuer tant que l’arrêt du verrouillage d’opération n’est pas terminé et que CompletionRoutine n’a pas été spécifié, le thread de l’appelant est bloqué et FsRtlCheckOplockEx2 ne retourne que lorsque l’arrêt du verrouillage d’opération est terminé.

Si le thread de l’appelant est bloqué et que NotifyRoutine n’a pas la valeur NULL, NotifyRoutine est appelé pour toutes les raisons suivantes définies dans NotifyParams :

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

L’appel à NotifyRoutine pour l’une des raisons ci-dessus se produit uniquement si CompletionRoutine a la valeur NULL et qu’il est nécessaire de bloquer le thread de l’appelant pour attendre la fin de l’arrêt.

Si NotifyRoutine est appelé pour une raison OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT, il est toujours appelé pour une raison OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED si l’attente se termine/se termine pour une raison quelconque (ce qui peut ne jamais être).

FsRtlCheckOplockEx2 ignore les codes OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT et OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED status retournés par NotifyRoutine.

Un PostIrpRoutine doit être spécifié uniquement si un CompletionRoutine a été spécifié. Lorsque PostIrpRoutine n’a pas la valeur NULL, il est appelé avant que quelque chose ne soit mis en file d’attente dans la file d’attente Irp.

Si l’indicateur OPLOCK_FLAG_PARENT_OBJECT est spécifié dans Indicateurs, FsRtlCheckOplockEx2 interrompt inconditionnellement tout oplock parent existant ; autrement dit, le code principal de l’Irp n’est pas pris en compte.

Si un système de fichiers utilise des oplocks, il doit appeler FsRtlCheckOplockEx2 à partir de toutes les routines de répartition pour les opérations d’E/S qui peuvent provoquer des interruptions d’oplock. Cette règle s’applique aux types d’opérations d’E/S suivants, car ces opérations peuvent provoquer des blocages d’opération :