Fonction FltAllocateContext (fltkernel.h)

Article
03/19/2024

La routine FltAllocateContext alloue une structure de contexte pour un type de contexte spécifié.

Syntaxe

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

Paramètres

[in] Filter

Pointeur de filtre opaque pour l’appelant. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[in] ContextType

Valeur FLT_CONTEXT_TYPE qui indique le type de contexte à allouer. ContextType peut être l’un des éléments suivants :

Valeur	Signification
FLT_VOLUME_CONTEXT (0x0001)	Allouez un contexte de volume.
FLT_INSTANCE_CONTEXT (0x0002)	Allouez un contexte instance.
FLT_FILE_CONTEXT (0x0004)	Allouez un contexte de fichier.
FLT_STREAM_CONTEXT (0x0008)	Allouez un contexte de flux.
FLT_STREAMHANDLE_CONTEXT (0x0010)	Allouez un contexte de handle de flux.
FLT_TRANSACTION_CONTEXT (0x0020)	Allouez un contexte de transaction.
FLT_SECTION_CONTEXT (0x0040)	Allouez un contexte de section. Disponible à partir de Windows 8.

[in] ContextSize

Taille, en octets, de la partie du contexte définie par le pilote de minifiltre. Doit être supérieur à zéro et inférieur ou égal à MAXUSHORT ; pour les contextes de taille fixe, doit être inférieur ou égal à la taille spécifiée dans la structure FLT_CONTEXT_REGISTRATION . Un minifiltre utilise cette partie du contexte pour conserver des informations de contexte spécifiques à lui-même. FltMgr traite cette partie de la structure de contexte comme opaque. Ce paramètre est obligatoire et ne peut pas être égal à zéro.

[in] PoolType

Type de pool à allouer. Ce paramètre est obligatoire et doit être l’un des éléments suivants. Consultez POOL_TYPE pour obtenir une description détaillée de chaque type. Pour plus d'informations, consultez la section Notes.

Valeur	Signification
NonPagedPool	Mémoire système non pagéable. PoolType doit être NonPagedPool si ContextType est FLT_VOLUME_CONTEXT.
PagedPool	Mémoire système paginable.
NonPagedPoolNx	Pool non paginé no-execute (NX).

[out] ReturnedContext

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse du contexte nouvellement alloué. L’appelant est responsable de l’appel de FltReleaseContext pour libérer ce contexte lorsqu’il n’est plus nécessaire.

Valeur retournée

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

Code de retour	Description
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	Les informations d’allocation pour le contexte du type spécifié n’étaient pas fournies au moment de l’inscription du filtre. OR, pour les contextes de taille fixe, la taille de contexte demandée est supérieure à la taille spécifiée dans la structure FLT_CONTEXT_REGISTRATION pour le ContextType spécifié.
STATUS_FLT_DELETING_OBJECT	Le pilote de minifiltre spécifié dans le paramètre Filter est en cours de démonté. Il s’agit d’un code d’erreur.
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_BUFFER_SIZE	ContextSize ne peut pas être supérieur à MAXUSHORT. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	Une valeur non valide a été spécifiée pour le paramètre ContextType ou ContextSize . Il s’agit d’un code d’erreur.
STATUS_NOT_SUPPORTED	Le système de fichiers ne prend pas en charge les contextes par flux. Il s’agit d’un code d’erreur.

Remarques

Pour plus d’informations sur les contextes, consultez À propos des contextes de minifiltre.

FltAllocateContext alloue un contexte du type spécifié à partir du pool spécifié. À compter de Windows 11, si la mémoire vers laquelle renvoie ReturnedContext est zéro dépend de ce qui suit :

La mémoire est garantie pour être mise à zéro pour les contextes de taille variable.
Le contenu de la mémoire est défini par l’implémentation pour les contextes de taille fixe alloués par une fonction de rappel fournie par l’appelant.
Sinon, la mémoire ne peut pas être supposée être mise à zéro pour les contextes de taille fixe en raison du comportement de liste de recherche. Autrement dit, une entrée renvoyée à partir de la liste de lookaside peut ne pas être zéro si c’est la mémoire qui a été précédemment libérée dans la liste de lookaside par opposition à une nouvelle allocation.

Avant Windows 11, le contenu du contexte retourné n’est pas zéro.

Si vous définissez PoolType sur une valeur non valide, vous risquez d’avoir un comportement inattendu, par exemple, de contourner les listes de recherche, ce qui entraîne la perte des avantages en matière de performances des listes de recherche. Pour les contextes qui ont une fonction de rappel ContextAllocateCallback , le comportement dû à un PoolType non valide dépend de l’implémentation.

Une fois le contexte alloué, il peut être défini sur un objet en passant le pointeur ReturnedContext à la routine set-context appropriée à partir du tableau suivant.

Type de contexte	Set-Context Routine
FLT_FILE_CONTEXT	FltSetFileContext (à partir de Windows Vista)
FLT_INSTANCE_CONTEXT	FltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan (à partir de Windows 8)
FLT_STREAM_CONTEXT	FltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltSetTransactionContext (à partir de Windows Vista)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

Lorsqu’un pilote de minifiltre appelle FltRegisterFilter à partir de sa routine DriverEntry , il doit inscrire chaque type de contexte qu’il utilise. Pour plus d’informations, consultez l’entrée de référence pour la structure FLT_CONTEXT_REGISTRATION et l’inscription des types de contexte.

FltAllocateContext n’initialise pas le contenu de la partie de la structure de contexte spécifique au pilote minifilter.

Pour obtenir le contexte d’un objet, appelez FltGetContexts ou la routine get-context appropriée à partir du tableau suivant.

Type de contexte	Get-Context Routine
FLT_FILE_CONTEXT	FltGetFileContext (à partir de Windows Vista)
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext (à partir de Windows 8)
FLT_STREAM_CONTEXT	FltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext (à partir de Windows Vista )
FLT_VOLUME_CONTEXT	FltGetVolumeContext

Les contextes sont comptés en référence et, lors d’un retour réussi de FltAllocateContext, le contexte pointé par ReturnedContext a été initialisé pour avoir un nombre de références de 1. Un contexte est libéré automatiquement lorsque son nombre de références atteint zéro. Pour incrémenter le nombre de références sur un contexte, appelez FltReferenceContext.

Pour décrémenter le nombre de références sur un contexte, appelez FltReleaseContext.

Étant donné que les contextes sont comptés en références, il n’est généralement pas nécessaire de les supprimer. Pour supprimer un contexte explicitement, appelez FltDeleteContext ou la routine delete-context appropriée dans le tableau suivant.

Type de contexte	Delete-Context Routine
FLT_FILE_CONTEXT	FltDeleteFileContext (à partir de Windows Vista)
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan (à compter de Windows 8)
FLT_STREAM_CONTEXT	FltDeleteStreamContext
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext (à partir de Windows Vista)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext