FltAllocateCallbackData, fonction (fltkernel.h)

Article
02/06/2025

FltAllocateCallbackData alloue une structure de données de rappel qu’un pilote minifilter peut utiliser pour lancer une requête 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 d’instance opaque pour l’instance de pilote minifilter qui lance l’opération d’E/S. Ce paramètre est obligatoire et ne peut pas être NULL.

[in, optional] FileObject

Pointeur d’objet de 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 nouvellement allouées (FLT_CALLBACK_DATA).

Valeur de retour

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

Retourner le code	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 minifilter 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 minifilter.

Remarque La routine FltAllocateCallbackData n’alloue pas toutes les mémoires qui peuvent être requises par une requête d’E/S ultérieure. Si une requête d’E/S, telle que FltPerformSynchronousIo ou FltPerformAsynchronousIo, nécessite une mémoire supplémentaire pour une certaine structure, la requête peut rencontrer une allocation de mémoire. La routine FltAllocateCallbackDataEx peut être utilisée pour éviter ce problème potentiel en préaffectant la mémoire pour les structures supplémentaires à utiliser dans une requête 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 de 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 minifilter attachées sous l’instance de lancement (spécifiée dans le paramètre Instance) et au système de fichiers. Les pilotes Minifilter attachés au-dessus de l’instance spécifiée ne reçoivent pas l’opération d’E/S.

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

Les pilotes Minifilter doivent utiliser FltAllocateCallbackData, FltPerformAsynchronousIoet FltPerformSynchronousIo uniquement pour les opérations d’E/S pour lesquelles les 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 le libérer en appelant FltFreeCallbackData.