Partager via


FltCheckOplockEx, fonction (fltkernel.h)

Un pilote minifilter appelle la routine FltCheckOplockEx pour synchroniser la structure de données de rappel pour une opération d’E/S de fichier basée sur IRP qui a l’état actuel du verrou opportuniste (oplock) du fichier.

Syntaxe

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplockEx(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in]           ULONG                                   Flags,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

Paramètres

[in] Oplock

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

[in] CallbackData

Pointeur vers la structure des données de rappel FLT_CALLBACK_DATApour l’opération d’E/S.

[in] Flags

Masque de bits pour l’opération d’E/S de fichier associée. Un pilote minifilter définit des bits pour spécifier le comportement de FltCheckOplockEx. Le paramètre indicateurs de contient les options suivantes :

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

Permet à un saut de verrou opportuniste de continuer sans bloquer ou en attente l’opération qui a provoqué l’arrêt d’oplock.

OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)

Spécifie que FltCheckOplockEx ne doit vérifier qu’une clé de verrouillage opportuniste sur l’FILE_OBJECT associée à l’opération d’E/S. Ces opérations d’E/S sont représentées par les données de rappel auxquelles pointe le paramètre CallbackData. FltCheckOplockEx devez ensuite ajouter la clé si celle-ci est fournie dans l’opération d’E/S. Aucun autre traitement oplock ne se produit ; c’est-à-dire qu’aucune coupure de verrou opportuniste ne se produira.

OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)

Spécifie que FsRtlCheckOplockEx doit rétablir tout état précédemment configuré via un appel à la routine FltOplockFsctrl. FltOplockFsctrl est appelée lorsqu’une demande de IRP_MJ_CREATE est traitée. Cette requête IRP_MJ_CREATE spécifie l’indicateur FILE_OPEN_REQUIRING_OPLOCK dans le paramètre d’options de création. 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)

Permet à tous les sauts de verrou opportunistes de continuer indépendamment de la clé de verrouillage opportuniste.

[in, optional] Context

Pointeur vers lequel les informations de contexte définies par l’appelant doivent être transmises aux routines de rappel qui WaitCompletionRoutine et PrePostCallbackDataRoutine point à. Le Gestionnaire de filtres traite ces informations comme opaques.

[in, optional] WaitCompletionRoutine

Pointeur vers une routine de rappel fournie par l’appelant. Si un saut d’oplock est en cours, le Gestionnaire de filtre appelle cette routine lorsque le saut d’oplock est terminé. Ce paramètre est facultatif et peut être NULL. S’il s’agit NULL, l’appelant est placé dans un état d’attente jusqu’à ce que l’arrêt d’oplock soit terminé.

Cette routine est déclarée comme suit :

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

Cette routine a les paramètres suivants :

CallbackData

Pointeur vers la structure de données de rappel pour l’opération d’E/S.

Remarque que lorsque votre WaitCompleteRoutine est appelé, la sous-structure IoStatus peut être remplie avec un état d’échec (par exemple, STATUS_CANCELLED). Vous devez inspecter cet état et réagir de manière appropriée.

Contexte

Pointeur d’informations de contexte qui a été passé dans le paramètre Context à FltCheckOplockEx.

[in, optional] PrePostCallbackDataRoutine

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
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

CallbackData

Pointeur vers la structure de données de rappel pour l’opération d’E/S.

Contexte

Pointeur d’informations de contexte qui a été passé dans le paramètre Context à FltCheckOplockEx.

Valeur de retour

FltCheckOplockEx retourne l’un des codes de FLT_PREOP_CALLBACK_STATUS suivants :

Retourner le code Description
FLT_PREOP_COMPLETE
FltCheckOplockEx a rencontré un échec d’allocation de pool, ou un appel à la fonction FsRtlCheckOplockEx a renvoyé une erreur. FltCheckOplockEx définit le code d’erreur dans le membre Status de la structure IO_STATUS_BLOCK de la structure IoStatus membre de la structure de données de rappel FLT_CALLBACK_DATA. Le paramètre CallbackData pointe vers cette structure FLT_CALLBACK_DATA.
FLT_PREOP_PENDING
Un arrêt d’oplock a été lancé, ce qui a provoqué la publication de l’opération d’E/S dans une file d’attente de travail. L’opération d’E/S est représentée par les données de rappel auxquelles pointe le paramètre CallbackData.
FLT_PREOP_SUCCESS_WITH_CALLBACK
Les données de rappel auxquelles le CallbackData points de paramètre à ne pas avoir été suspendus et l’opération d’E/S a été effectuée immédiatement. N’oubliez pas que si l’appelant a spécifié OPLOCK_FLAG_COMPLETE_IF_OPLOCKED dans le paramètre Indicateurs, un saut d’oplock peut être en cours même si l’opération d’E/S n’a pas été bloquée. Pour déterminer s’il s’agit de la situation, l’appelant doit vérifier STATUS_OPLOCK_BREAK_IN_PROGRESS dans le membre Status de la structure IO_STATUS_BLOCK de la structure IoStatus membre de la structure de données de rappel FLT_CALLBACK_DATA.

Remarques

Un pilote minifilter appelle FltCheckOplockEx pour synchroniser une opération d’E/S basée sur IRP avec l’état d’oplock actuel d’un fichier en fonction des conditions suivantes :

  • Si l’opération d’E/S provoque l’arrêt de l’oplock, le saut d’oplock est lancé.

  • Si l’opération d’E/S ne peut pas continuer tant que l’arrêt d’oplock n’est pas terminé, FltCheckOplockEx retourne FLT_PREOP_PENDING et appelle la routine de rappel vers laquelle pointe le paramètre PrePostCallbackDataRoutine.

  • Si un pilote minifilter utilise des oplocks, il doit appeler FltCheckOplockEx à partir de n’importe quelle routine de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) pour les opérations d’E/S qui peuvent provoquer des sauts d’oplock. Cette règle s’applique aux types d’opérations d’E/S suivants, car ces opérations peuvent entraîner des sauts d’oplock :

    • 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

L’opération d’E/S doit être une opération d’E/S basée sur IRP. Pour déterminer si une structure de données de rappel donnée représente une opération d’E/S basée sur IRP, utilisez la macro FLT_IS_IRP_OPERATION.

Les minifilters ne doivent pas appeler FltCheckOplockEx à nouveau dans le rappel spécifié dans WaitCompletionRoutine. Cela peut entraîner une condition d’interblocage si le package oplock appelle le rappel d’achèvement avant FltCheckOplockEx retourne.

Pour plus d’informations sur les verrous opportunistes, consultez la documentation du Kit de développement logiciel (SDK) Microsoft Windows.

Exigences

Exigence Valeur
client minimum pris en charge La routine FltCheckOplockEx est disponible à partir de Windows 7.
plateforme cible Universel
d’en-tête fltkernel.h (include Fltkernel.h)
bibliothèque FltMgr.lib
IRQL <= APC_LEVEL

Voir aussi

FLT_CALLBACK_DATA

FLT_IS_IRP_OPERATION

FltInitializeOplock

FltOplockFsctrl

FsRtlCheckOplockEx

IO_STATUS_BLOCK

PFLT_PRE_OPERATION_CALLBACK