Fonction FsRtlCheckOplockEx (ntifs.h)

Article
09/27/2023

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

Syntaxe

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

Paramètres

[in] Oplock

Pointeur de verrou opportuniste opaque pour le fichier. Ce pointeur doit avoir été initialisé par un appel précédent à FsRtlInitializeOplock.

[in] Irp

Pointeur vers l’IRP pour l’opération d’E/S.

[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 FsRtlCheckOplockEx. Le paramètre Flags comporte les options suivantes :

Valeur	Signification
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Spécifie pour permettre à un arrêt de verrouillage opportuniste de se poursuivre sans bloquer ou attendre l’opération à l’origine de l’arrêt de l’opération.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Pris en charge à partir de Windows 7. Spécifie que FsRtlCheckOplockEx doit uniquement case activée pour une clé de verrouillage opportuniste sur le FILE_OBJECT associé à l’IRP vers lequel pointe le paramètre Irp. FsRtlCheckOplockEx 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 verrou opportuniste ne se produira.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Pris en charge à partir de Windows 7. Spécifie que FsRtlCheckOplockEx 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.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Pris en charge à partir de Windows 7. Spécifie pour permettre à tous les sauts de verrou opportunistes de se poursuivre, quelle que soit la clé de verrouillage opportuniste.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Pris en charge à partir de Windows 8. Spécifie qu’Oplock est associé au parent (répertoire) du fichier ou du répertoire vers lequel l’IRP dans le paramètre Irp est dirigé.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Pris en charge à partir de Windows 8. Spécifie que l’opération d’E/S spécifiée dans Irp est une 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 verrou opportuniste.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Pris en charge à partir de Windows 8. Spécifie la gestion d’un saut de verrou opportuniste 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.

[in, optional] Context

Pointeur vers les informations de contexte définies par l’appelant à passer aux routines de rappel auxquelles pointent les paramètres CompletionRoutine et PostIrpRoutine .

[in, optional] CompletionRoutine

Pointeur vers une routine de rappel fournie par l’appelant. Si un verrou opportuniste est en cours, cette routine est appelée une fois l’arrêt terminé. Ce paramètre est facultatif et peut être NULL. S’il est NULL, l’appelant est placé dans un état d’attente jusqu’à ce que le verrou opportuniste soit terminé.

Cette routine est déclarée comme suit :

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

Cette routine a les paramètres suivants :

Paramètre	Description
Context	Pointeur d’informations de contexte qui a été passé dans le paramètre Context à FsRtlCheckOplockEx.
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.

Cette routine est déclarée comme suit :

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

Cette routine a les paramètres suivants :

Paramètre	Description
Context	Pointeur d’informations de contexte qui a été passé dans le paramètre Context à FsRtlCheckOplockEx.
Irp	Pointeur vers l’IRP pour l’opération d’E/S.

Valeur retournée

FsRtlCheckOplockEx retourne STATUS_SUCCESS ou un code NTSTATUS approprié comme 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	L’arrêt de verrou opportuniste (oplock) ne peut pas être effectué. L’IRP est une requête 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 verrou opportuniste 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 verrou opportuniste a été rompu.
STATUS_PENDING	Un saut de verrou opportuniste a été lancé et le contrôle de l’IRP a été passé au package oplock. Si CompletionRoutine a la valeur NULL, cette routine est bloquée pendant le traitement de l’arrêt d’opération, plutôt que de retourner STATUS_PENDING. STATUS_PENDING est un code de réussite.

Remarques

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

Si l’opération d’E/S entraîne l’arrêt du verrou opportuniste, l’arrêt de verrouillage opportuniste est lancé.
Si l’opération d’E/S ne peut pas continuer tant que l’arrêt de verrouillage opportuniste n’est pas terminé et qu’une routine d’achèvement dans CompletionRoutine n’a pas été spécifiée, FsRtlCheckOplockEx retourne STATUS_PENDING et appelle la routine de rappel spécifiée dans PostIrpRoutine. Lorsque l’arrêt de verrouillage opportuniste a été reconnu, la routine de rappel dans CompletionRoutine est appelée.
Si l’opération d’E/S ne peut pas se poursuivre tant que le verrou opportuniste n’est pas terminé et que CompletionRoutine n’a pas été spécifié, FsRtlCheckOplockEx ne retourne pas tant que l’arrêt de verrouillage opportuniste n’est pas reconnu.

Un PostIrpRoutine doit être spécifié uniquement si un CompletionRoutine a été spécifié.

Si un système de fichiers ou un pilote de filtre utilise des verrous opportunistes, il doit appeler FsRtlCheckOplockEx à partir de toutes les routines de répartition pour les opérations d’E/S qui peuvent provoquer des arrêts de verrouillage opportunistes. Cette règle s’applique aux types d’opérations d’E/S suivants, car ces opérations peuvent provoquer des blocages opportunistes :

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

Pour plus d’informations sur les verrous opportunistes, consultez la documentation Microsoft Windows SDK.

Les minifiltres doivent appeler FltCheckOplockEx au lieu de FsRtlCheckOplockEx.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL