Lire en anglais

Partager via


FltAllocateContext, fonction (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 être NULL.

[in] ContextType

Valeur FLT_CONTEXT_TYPE qui indique le type de contexte à allouer. ContextType peut être l’une des options suivantes :

Valeur Signification
FLT_VOLUME_CONTEXT (0x0001) Allouez un contexte de volume.
FLT_INSTANCE_CONTEXT (0x0002) Allouez un contexte d’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éfini par le pilote minifilter. Doit être supérieur à zéro et inférieur ou égal à MAXUSHORT ; pour les contextes de taille fixe, doit être inférieur ou égal à l'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 à elle-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 les remarques.

Valeur Signification
NonPagedPool Mémoire système non modifiable. PoolType doit être NonPagedPool si ContextType est FLT_VOLUME_CONTEXT.
pagedPool Mémoire système paginable.
nonPagedPoolNx Pool non exécuté (NX) non paginé.

[out] ReturnedContext

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

Valeur de retour

FltAllocateContext retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’une des valeurs suivantes :

Retourner le code Description
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND Les informations d’allocation pour le contexte du type spécifié n’ont pas été fournies au moment de l’inscription de filtre. OR, pour les contextes de taille fixe, le ContextSize demandé est supérieur à l'Size spécifié dans la structure FLT_CONTEXT_REGISTRATION pour le ContextType spécifié.
STATUS_FLT_DELETING_OBJECT Le pilote minifilter spécifié dans le paramètre Filter est détruit. Il s’agit d’un code d’erreur.
STATUS_INSUFFICIENT_RESOURCES FltAllocateContext 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 ContextType ou le paramètre 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 minifilter.

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

  • La mémoire est garantie d’être 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 considérée comme zéro pour les contextes de taille fixe en raison du comportement de liste de lookaside. Autrement dit, une entrée retournée à partir de la liste lookaside peut ne pas être zéro si elle est la mémoire précédemment libérée à la liste de lookasides par opposition à une nouvelle allocation.

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

La définition de PoolType à une valeur non valide peut entraîner un comportement inattendu, tel que l’origine de la déviation des listes de lookasides, ce qui entraîne la perte des avantages en termes de performances des listes lookaside. Pour les contextes qui ont un ContextAllocateCallback fonction de rappel, le comportement en raison 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 de contexte défini appropriée à partir du tableau suivant.

Type de contexte routine Set-Context
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 minifilter 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 Types de contexte d’inscription.

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 routine Get-Context
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 comptabilisés par référence et, lors d’un retour réussi de FltAllocateContext, le contexte pointé par ReturnContext 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 comptabilisés de référence, il n’est généralement pas nécessaire de les supprimer. Pour supprimer un contexte explicitement, appelez FltDeleteContext ou la routine de contexte de suppression appropriée du tableau suivant.

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

Exigences

Exigence Valeur
plateforme cible Universel
d’en-tête fltkernel.h (include 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