PFLT_PRE_OPERATION_CALLBACK fonction de rappel (fltkernel.h)
La routine de PFLT_PRE_OPERATION_CALLBACK d’un pilote minifilter 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 des données de rappel (FLT_CALLBACK_DATA) pour l’opération d’E/S.
[in] FltObjects
Pointeur vers une structure FLT_RELATED_OBJECTS qui contient des pointeurs opaques pour les objets liés à la requête 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 de retour
Cette routine de rappel retourne l’une des valeurs de FLT_PREOP_CALLBACK_STATUS suivantes.
| Retourner le code | Description |
|---|---|
| FLT_PREOP_COMPLETE | Le minifilter termine l’opération d’E/S. Pour plus d’informations, consultez les remarques. |
| FLT_PREOP_DISALLOW_FASTIO | L’opération est une opération d’E/S rapide, et le minifilter n’autorise pas l’utilisation du chemin d’E/S rapide pour cette opération. Pour plus d’informations, consultez les remarques. |
| FLT_PREOP_PENDING | Le minifilter a suspendu l’opération d’E/S et l’opération est toujours en attente. Pour plus d’informations, consultez les remarques. |
| 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’appelle pas le rappel post-opération du pilote minifilter, s’il en existe un, pendant l’achèvement 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 minifilter pendant l’achèvement des E/S. |
| FLT_PREOP_SYNCHRONIZE | Le minifilter retourne l’opération d’E/S à fltMgr pour un traitement ultérieur, mais il ne termine pas l’opération. Pour plus d’informations, consultez les remarques. |
| FLT_PREOP_DISALLOW_FSFILTER_IO | Le minifilter désalloue une opération QueryOpen rapide et force l’opération à descendre le chemin lent. Ainsi, le gestionnaire d’E/S est chargé de traiter la requête en effectuant une ouverture/requête/fermeture du fichier. Les pilotes Minifilter ne doivent retourner cet état que 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 minifilter 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 minifilter inscrit 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 minifilter transmet cette structure en tant que paramètre à FltRegisterFilter dans sa routine DriverEntry. Un minifilter peut inscrire une routine de rappel de pré-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.
Une routine de rappel de pré-opération ou post-opération d’un pilote minifilter peut modifier le contenu de la structure de données de rappel pour l’opération. Si c’est le cas, elle doit ensuite appeler FltSetCallbackDataDirty, sauf si elle a modifié le contenu de la structure de données de rappel champ IoStatus.
Le runtime d’intégration pour cette routine de rappel générique dépend de ses chemins d’E/S spécifiques. Vous pouvez appeler rapidement et peu cher KeGetCurrentIRQL si vous avez besoin de connaître le runtime d’intégration actuel. Consultez écriture de routines de rappel de pré-opération pour plus d’informations sur IRQL.
Les systèmes de fichiers arrondissent les opérations d’écriture et de lecture à la fin du fichier à un multiple de la taille du secteur de l’appareil 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 jusqu’à 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épasse la longueur allouée de la mémoire tampon. Pour plus d’informations sur l’échange de mémoires tampons, consultez l’exemple SwapBuffers Minifilter.
À 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 pour le rappel avec l’annotation de 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 de la structure de données de rappel IoStatus.Status sur la valeur NTSTATUS finale de 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 minifilter sous l’appelant dans la pile des pilotes ou au système de fichiers. Dans ce cas, FltMgr appelle uniquement les routines de rappel post-opération des pilotes minifilter au-dessus de l’appelant dans la pile des pilotes.
Retour de FLT_PREOP_DISALLOW_FASTIO
Si cette routine retourne FLT_PREOP_DISALLOW_FASTIO, elle ne doit pas définir le champ de la structure de données de rappel IoStatus.Status, 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 minifilter sous l’appelant dans la pile des pilotes ou au système de fichiers. Dans ce cas, FltMgr appelle uniquement les routines de rappel post-opération des pilotes minifilter au-dessus de l’appelant dans la pile des pilotes.
Retour de FLT_PREOP_PENDING
FLT_PREOP_PENDING ne peut être retourné 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 pendées. 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 l’opération d’E/S tant que le pilote minifilter n’appelle FltCompletePendedPreOperation.
Retour de FLT_PREOP_SYNCHRONIZE
Si la routine de rappel de pré-opération d’un minifilter retourne FLT_PREOP_SYNCHRONIZE, le minifilter 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 minifilter dans le contexte du thread actuel au <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 Minifilter 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 mini-filtres ne doivent jamais retourner FLT_PREOP_SYNCHRONIZE pour les opérations de lecture et d’écriture asynchrones. Cela peut dégrader gravement les performances du pilote mini-filtre et du système.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Correctif cumulatif Microsoft Windows 2000 1 pour SP4, Windows XP SP2, Windows Server 2003 SP1 et versions ultérieures. |
| plateforme cible | Bureau |
| d’en-tête | fltkernel.h (include FltKernel.h) |
| IRQL | Voir la section Remarques |