FltAllocateContext, fonction (fltkernel.h)
La routine FltAllocateContext alloue une structure de contexte pour un type de contexte spécifié.
NTSTATUS FLTAPI FltAllocateContext(
[in] PFLT_FILTER Filter,
[in] FLT_CONTEXT_TYPE ContextType,
[in] SIZE_T ContextSize,
[in] POOL_TYPE PoolType,
[out] PFLT_CONTEXT *ReturnedContext
);
[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.
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. |
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 |
Exigence | Valeur |
---|---|
plateforme cible | Universel |
d’en-tête | fltkernel.h (include Fltkernel.h) |
bibliothèque | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | <= APC_LEVEL |