Fonction FltCheckOplockEx (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 basée sur un fichier IRP qui a l’état actuel de verrouillage 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 FLT_CALLBACK_DATAdonnées de rappel pour 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 Flags a les options suivantes :
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)
Permet à un arrêt de verrouillage opportuniste de se poursuivre sans bloquer ou en attente de l’opération qui a provoqué l’arrêt de l’opération.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)
Spécifie que FltCheckOplockEx doit case activée uniquement pour une clé de verrouillage opportuniste sur le FILE_OBJECT associé à l’opération d’E/S. Ces opérations d’E/S sont représentées par les données de rappel vers laquelle pointe le paramètre CallbackData . FltCheckOplockEx doit ensuite ajouter la clé si une clé est fournie dans l’opération d’E/S. Aucun autre traitement oplock ne se produit ; c’est-à-dire qu’aucun 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é lorsqu’une demande de IRP_MJ_CREATE est traitée. Cette demande IRP_MJ_CREATE 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)
Permet à tous les verrous opportunistes de se poursuivre, quelle que soit la clé de verrouillage opportuniste.
[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 à 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.
Context
Pointeur d’informations de contexte qui a été passé dans le paramètre Context à FltCheckOplockEx.
Valeur retournée
FltCheckOplockEx retourne l’un des codes FLT_PREOP_CALLBACK_STATUS suivants :
| Code de retour | Description |
|---|---|
|
FltCheckOplockEx a rencontré un échec d’allocation de pool ou un appel à la fonction FsRtlCheckOplockEx a retourné une erreur. FltCheckOplockEx 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 structure FLT_CALLBACK_DATA. |
|
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 . |
|
Les données de rappel vers laquelle pointe le paramètre CallbackData n’ont pas é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 Flags , un blocage d’opération peut être en cours même si l’opération d’E/S n’a pas été suspendu. Pour déterminer si c’est le cas, l’appelant doit case activée pour STATUS_OPLOCK_BREAK_IN_PROGRESS 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 FltCheckOplockEx 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 verrouillage d’opération 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 toute routine de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) pour les opérations d’E/S susceptibles de provoquer des interruptions de verrouillage. 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 FltCheckOplockEx 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 FltCheckOplockEx .
Pour plus d’informations sur les verrous opportunistes, consultez la documentation Microsoft Windows SDK.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | La routine FltCheckOplockEx est disponible à partir de Windows 7. |
| Plateforme cible | Universal |
| En-tête | fltkernel.h (inclure Fltkernel.h) |
| Bibliothèque | FltMgr.lib |
| IRQL | <= APC_LEVEL |