Partager via


Fonction FltAllocateContext (fltkernel.h)

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

Configuration requise

Condition requise Valeur
Plateforme cible Universal
En-tête fltkernel.h (inclure Fltkernel.h)
Bibliothèque FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Voir aussi

FLT_CONTEXT_REGISTRATION

FltCloseSectionForDataScan

FltCreateSectionForDataScan

FltDeleteContext

FltDeleteFileContext

FltDeleteInstanceContext

FltDeleteStreamContext

FltDeleteStreamHandleContext

FltDeleteTransactionContext

FltDeleteVolumeContext

FltGetContexts

FltGetFileContext

FltGetInstanceContext

FltGetSectionContext

FltGetStreamContext

FltGetStreamHandleContext

FltGetTransactionContext

FltGetVolumeContext

FltReferenceContext

FltRegisterFilter

FltReleaseContext

FltSetFileContext

FltSetInstanceContext

FltSetStreamContext

FltSetStreamHandleContext

FltSetTransactionContext

FltSetVolumeContext