Fonction FltCheckOplock (fltkernel.h)

Article
03/01/2024

Un pilote de minifiltre appelle FltCheckOplock pour synchroniser la structure des données de rappel pour une opération d’E/S de fichier basée sur IRP avec l’état actuel du verrou opportuniste (oplock) du fichier.

Syntaxe

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplock(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [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 de données de rappel (FLT_CALLBACK_DATA) pour l’opération d’E/S.

[in, optional] Context

Pointeur vers les informations de contexte définies par l’appelant à passer aux routines de rappel vers laquelle WaitCompletionRoutine et PrePostCallbackDataRoutine pointent. Le Gestionnaire de filtres traite ces informations comme opaques.

[in, optional] WaitCompletionRoutine

Pointeur vers une routine de rappel fournie par l’appelant. Si un blocage d’opération est en cours, le Gestionnaire de filtres appelle cette routine lorsque l’arrêt du blocage d’opération est terminé. Ce paramètre est facultatif et peut être NULL. S’il a la valeur NULL, l’appelant est placé dans un état d’attente jusqu’à ce que l’arrêt du blocage d’opération 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.

Context

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

[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.

Context

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

Valeur retournée

FltCheckOplock retourne l’un des codes FLT_PREOP_CALLBACK_STATUS suivants :

Code de retour	Description
FLT_PREOP_COMPLETE	FltCheckOplock a rencontré un échec d’allocation de pool ou un appel à la fonction FsRtlCheckOplock a retourné une erreur. FltCheckOplock définit le code d’erreur dans le membre Status de la structure IO_STATUS_BLOCK du membre IoStatus de la structure de données de rappel FLT_CALLBACK_DATA . Le paramètre CallbackData pointe vers cette FLT_CALLBACK_DATA.
FLT_PREOP_PENDING	Un arrêt d’opération de verrouillage a été lancé, ce qui a entraîné le gestionnaire de filtres à publier 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 vers laquelle pointe le paramètre CallbackData .
FLT_PREOP_SUCCESS_WITH_CALLBACK	L’opération d’E/S a été effectuée immédiatement. N’oubliez pas que si cette opération était une opération de création qui spécifiait FILE_COMPLETE_IF_OPLOCKED dans le paramètre create-options, il peut y avoir en fait un blocage d’opération en cours même si l’opération a été effectuée immédiatement. Pour déterminer s’il s’agit de la situation, l’appelant doit case activée le status dans le membre Status de la structure IO_STATUS_BLOCK du membre IoStatus de la structure de données de rappel FLT_CALLBACK_DATA.

Remarques

Un pilote minifilter appelle FltCheckOplock pour synchroniser une opération d’E/S basée sur IRP 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 blocage d’opération n’est pas terminé, FltCheckOplock 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 FltCheckOplock à partir de toutes les routines de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) pour les opérations d’E/S qui peuvent provoquer des blocages d’opération. 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 :

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 à nouveau FltCheckOplock 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 le retour de FltCheckOplock .

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