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 |