Fonction FltAllocateCallbackData (fltkernel.h)

Article
02/29/2024

FltAllocateCallbackData alloue une structure de données de rappel qu’un pilote de minifiltre peut utiliser pour lancer une demande d’E/S.

Syntaxe

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

Paramètres

[in] Instance

Pointeur de instance opaque pour le pilote de minifiltre instance qui lance l’opération d’E/S. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[in, optional] FileObject

Pointeur d’objet fichier à utiliser dans l’opération d’E/S. Ce paramètre est facultatif et peut être NULL.

[out] RetNewCallbackData

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse de la structure de données de rappel (FLT_CALLBACK_DATA) nouvellement allouée.

Valeur retournée

FltAllocateCallbackData retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData a rencontré un échec d’allocation de pool lors de la tentative d’allocation de la structure de données de rappel. Il s’agit d’un code d’erreur.

Remarques

Un pilote de minifiltre peut appeler FltAllocateCallbackData pour allouer une structure de données de rappel (FLT_CALLBACK_DATA) pour une opération d’E/S initiée par le pilote de minifiltre.

Note La routine FltAllocateCallbackData n’alloue pas toute la mémoire qui peut être requise par une demande d’E/S suivante. Si une demande d’E/S, telle que FltPerformSynchronousIo ou FltPerformAsynchronousIo, nécessite de la mémoire supplémentaire pour une structure, la demande peut rencontrer une allocation de mémoire. La routine FltAllocateCallbackDataEx peut être utilisée pour éviter ce problème potentiel en préallouant la mémoire pour des structures supplémentaires à utiliser dans une demande d’E/S. S’il existe un problème d’allocation de mémoire pour la structure RetNewCallbackData ou des structures requises supplémentaires, il peut être traité au point d’allocation des données de rappel.

Les structures de données de rappel sont allouées à partir d’un pool non paginé.

Après avoir initialisé les paramètres de la structure de données de rappel retournée par FltAllocateCallbackData, l’appelant lance l’opération d’E/S en passant la structure à FltPerformSynchronousIo ou FltPerformAsynchronousIo. Ces routines envoient l’opération d’E/S uniquement aux instances de pilote de minifiltre attachées sous la instance de lancement (spécifiée dans le paramètre Instance) et au système de fichiers. Les pilotes de minifiltre attachés au-dessus du instance spécifiés ne reçoivent pas l’opération d’E/S.

Les pilotes de minifiltre peuvent uniquement lancer des opérations d’E/S basées sur IRP. Ils ne peuvent pas lancer d’opérations de rappel rapides d’E/S ou de filtre de système de fichiers (FSFilter).

Les pilotes de minifiltre doivent utiliser FltAllocateCallbackData, FltPerformAsynchronousIo et FltPerformSynchronousIo uniquement pour les opérations d’E/S pour lesquelles des routines telles que les suivantes ne peuvent pas être utilisées :

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

Lorsque la structure de données de rappel allouée par FltAllocateCallbackData n’est plus nécessaire, l’appelant est chargé de la libérer en appelant FltFreeCallbackData.