Partager via


PFLT_PRE_OPERATION_CALLBACK fonction de rappel (fltkernel.h)

La routine de PFLT_PRE_OPERATION_CALLBACK d’un pilote de minifiltre effectue le traitement préopération pour les opérations d’E/S.

Syntaxe

PFLT_PRE_OPERATION_CALLBACK PfltPreOperationCallback;

FLT_PREOP_CALLBACK_STATUS PfltPreOperationCallback(
  [in, out] PFLT_CALLBACK_DATA Data,
  [in]      PCFLT_RELATED_OBJECTS FltObjects,
  [out]     PVOID *CompletionContext
)
{...}

Paramètres

[in, out] Data

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

[in] FltObjects

Pointeur vers une structure de FLT_RELATED_OBJECTS qui contient des pointeurs opaques pour les objets liés à la demande d’E/S actuelle.

[out] CompletionContext

Si cette routine de rappel retourne FLT_PREOP_SUCCESS_WITH_CALLBACK ou FLT_PREOP_SYNCHRONIZE, ce paramètre est un pointeur de contexte facultatif à passer à la routine de rappel post-opération correspondante. Sinon, elle doit être NULL.

Valeur retournée

Cette routine de rappel retourne l’une des valeurs FLT_PREOP_CALLBACK_STATUS suivantes.

Code de retour Description
FLT_PREOP_COMPLETE Le minifiltre termine l’opération d’E/S. Pour plus de détails, consultez la section Notes.
FLT_PREOP_DISALLOW_FASTIO L’opération est une opération d’E/S rapide, et le minifiltre n’autorise pas l’utilisation du chemin d’E/S rapide pour cette opération. Pour plus de détails, consultez la section Notes.
FLT_PREOP_PENDING Le minifiltre a suspendu l’opération d’E/S et l’opération est toujours en attente. Pour plus de détails, consultez la section Notes.
FLT_PREOP_SUCCESS_NO_CALLBACK Le minifiltre retourne l’opération d’E/S à FltMgr pour un traitement ultérieur. Dans ce cas, FltMgr n’appellera pas le rappel post-opération du pilote minifiltre, le cas échéant, pendant la fin des E/S.
FLT_PREOP_SUCCESS_WITH_CALLBACK Le minifiltre retourne l’opération d’E/S à FltMgr pour un traitement ultérieur. Dans ce cas, FltMgr appelle le rappel post-opération du minifiltre pendant la fin des E/S.
FLT_PREOP_SYNCHRONIZE Le minifiltre retourne l’opération d’E/S à FltMgr pour un traitement ultérieur, mais il ne termine pas l’opération. Pour plus de détails, consultez la section Notes.
FLT_PREOP_DISALLOW_FSFILTER_IO Le minifiltre interdit une opération QueryOpen rapide et force l’opération à descendre le chemin lent. Cela entraîne le gestionnaire d’E/S à traiter la demande en effectuant une ouverture/requête/fermeture du fichier. Les pilotes de minifiltre doivent uniquement renvoyer cette status pour QueryOpen.

Remarques

Pour plus d’informations, consultez Écriture de routines de rappel de pré-opération .

La routine de rappel de pré-opération d’un minifiltre traite un ou plusieurs types d’opérations d’E/S. (Cette routine de rappel est similaire à une routine de répartition dans le modèle de filtre hérité.)

Un minifiltre enregistre une routine de rappel de pré-opération pour un type particulier d’opération d’E/S en stockant le point d’entrée de la routine de rappel dans le tableau OperationRegistration de la structure FLT_REGISTRATION . Le minifiltre transmet cette structure en tant que paramètre à FltRegisterFilter dans sa routine DriverEntry . Un minifiltre peut inscrire une routine de rappel avant l’opération pour un type donné d’opération d’E/S sans inscrire une routine de rappel post-opération (PFLT_POST_OPERATION_CALLBACK) et vice versa.

La routine de rappel avant ou après l’opération d’un pilote minifiltre peut modifier le contenu de la structure de données de rappel pour l’opération. Si c’est le cas, il doit appeler FltSetCallbackDataDirty, sauf s’il a modifié le contenu du champ IoStatus de la structure de données de rappel.

L’IRQL de cette routine de rappel générique dépend de ses chemins d’E/S spécifiques. Vous pouvez rapidement et à moindre coût appeler KeGetCurrentIRQL si vous avez besoin de connaître l’IRQL actuel. Pour plus d’informations sur IRQL, consultez Écriture de routines de rappel de pré-opération .

Les systèmes de fichiers arrondissent les opérations d’écriture et de lecture à la fin du fichier à un multiple de la taille de secteur du périphérique de stockage de fichiers sous-jacent. Lors du traitement des opérations de pré-lecture ou de préécriture, les filtres qui allouent et échangent des mémoires tampons doivent arrondir la taille d’une mémoire tampon allouée à un multiple de la taille du secteur de l’appareil associé. Si ce n’est pas le cas, la longueur des données transférées à partir du système de fichiers sous-jacent dépassera la longueur allouée de la mémoire tampon. Pour plus d’informations sur l’échange de mémoires tampons, consultez l’exemple de minifiltre SwapBuffers.

À compter de Windows 8, CompletionContext utilise l’annotation Flt_CompletionContext_Outptr qui définit des valeurs de contexte valides en fonction du résultat de l’opération. Voici un exemple d’utilisation du rappel avec l’annotation pour CompletionContext.

FLT_PREOP_CALLBACK_STATUS
SwapPreReadBuffers(
    _Inout_ PFLT_CALLBACK_DATA Data,
    _In_ PCFLT_RELATED_OBJECTS FltObjects,
    _Flt_CompletionContext_Outptr_ PVOID *CompletionContext
    );


Retour de FLT_PREOP_COMPLETE

Si cette routine retourne FLT_PREOP_COMPLETE, elle doit définir le champ IoStatus.Status de la structure de rappel sur la valeur NTSTATUS finale pour l’opération d’E/S. Cette valeur NTSTATUS ne peut pas être STATUS_PENDING. Pour une opération de nettoyage ou de fermeture, il doit s’agir d’une valeur NTSTATUS réussie autre que STATUS_PENDING, car les opérations de nettoyage et de fermeture ne peuvent pas échouer.

Lorsque cette routine retourne FLT_PREOP_COMPLETE, FltMgr n’envoie pas l’opération d’E/S aux pilotes de minifiltre situés sous l’appelant dans la pile de pilotes ou au système de fichiers. Dans ce cas, FltMgr appelle uniquement les routines de rappel post-opération des pilotes de minifiltre au-dessus de l’appelant dans la pile de pilotes.

Retour de FLT_PREOP_DISALLOW_FASTIO

Si cette routine retourne FLT_PREOP_DISALLOW_FASTIO, elle ne doit pas définir le champ IoStatus.Status de la structure de données de rappel, car FltMgr définit automatiquement ce champ sur STATUS_FLT_DISALLOW_FAST_IO.

FLT_PREOP_DISALLOW_FASTIO ne peut être retourné que pour une opération d’E/S rapide. Pour déterminer si une structure de données de rappel donnée représente une opération d’E/S rapide, utilisez la macro FLT_IS_FASTIO_OPERATION .

Lorsque cette routine retourne FLT_PREOP_DISALLOW_FASTIO, FltMgr n’envoie pas l’opération d’E/S rapide aux pilotes de minifiltre en dessous de l’appelant dans la pile de pilotes ou au système de fichiers. Dans ce cas, FltMgr appelle uniquement les routines de rappel post-opération des pilotes de minifiltre au-dessus de l’appelant dans la pile de pilotes.

Retour de FLT_PREOP_PENDING

FLT_PREOP_PENDING ne peuvent être retournés que pour les opérations D’E/S basées sur IRP, car seules les opérations d’E/S basées sur IRP peuvent être suspendus. 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 .

Lorsque cette routine retourne FLT_PREOP_PENDING, FltMgr ne traite pas davantage l’opération d’E/S tant que le pilote de minifiltre n’appelle pas FltCompletePendedPreOperation.

Retour de FLT_PREOP_SYNCHRONIZE

Si la routine de rappel préalable à l’opération d’un minifiltre retourne FLT_PREOP_SYNCHRONIZE, le minifiltre doit avoir inscrit un rappel post-opération correspondant pour l’opération. Lorsque cette routine retourne FLT_PREOP_SYNCHRONIZE, FltMgr appelle le rappel post-opération du minifiltre dans le contexte du thread actuel à l’adresse IRQL <= APC_LEVEL.

FLT_PREOP_SYNCHRONIZE ne doit être retourné que pour les opérations D’E/S basées sur IRP. S’il est retourné pour une opération d’E/S qui n’est pas une opération basée sur IRP, FltMgr traite cette valeur de retour comme si elle était FLT_PREOP_SUCCESS_WITH_CALLBACK.

Les pilotes de minifiltre ne doivent pas retourner FLT_PREOP_SYNCHRONIZE pour les opérations de création, car ces opérations sont déjà synchronisées par FltMgr.

Les minifiltres ne doivent jamais retourner FLT_PREOP_SYNCHRONIZE pour les opérations asynchrones de lecture et d’écriture. Cela peut gravement dégrader à la fois le pilote de minifiltre et les performances du système.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Correctif cumulatif Microsoft Windows 2000 1 pour les systèmes d’exploitation Windows SP4, Windows XP SP2, Windows Server 2003 SP1 et versions ultérieures.
Plateforme cible Desktop (Expérience utilisateur)
En-tête fltkernel.h (inclure FltKernel.h)
IRQL Voir la section Remarques

Voir aussi

FLT_CALLBACK_DATA

FLT_IO_PARAMETER_BLOCK

FLT_IS_FASTIO_OPERATION

FLT_IS_IRP_OPERATION

FLT_IS_REISSUED_IO

FLT_IS_SYSTEM_BUFFER

FLT_REGISTRATION

FLT_RELATED_OBJECTS

FltCompletePendedPostOperation

FltCompletePendedPreOperation

FltQueueDeferredIoWorkItem

FltRegisterFilter

FltSetCallbackDataDirty

PFLT_POST_OPERATION_CALLBACK

Flt_CompletionContext_Outptr

KeGetCurrentIRQL