Fonction FltSetFileContext (fltkernel.h)

  • Article

La routine FltSetFileContext définit un contexte pour un fichier.

Syntaxe

NTSTATUS FLTAPI FltSetFileContext(
  [in]  PFLT_INSTANCE             Instance,
  [in]  PFILE_OBJECT              FileObject,
  [in]  FLT_SET_CONTEXT_OPERATION Operation,
  [in]  PFLT_CONTEXT              NewContext,
  [out] PFLT_CONTEXT              *OldContext
);

Paramètres

[in] Instance

Pointeur opaque vers un pilote minifilter instance pour l’appelant. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] FileObject

Pointeur vers un objet de fichier pour le fichier. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] Operation

Indicateur qui spécifie le type d’opération que FltSetFileContext doit effectuer. Ce paramètre doit être l’un des indicateurs suivants :

Indicateur Signification
FLT_SET_CONTEXT_REPLACE_IF_EXISTS Si un contexte est déjà défini pour le fichier vers lequel le paramètre FileObject pointe, FltSetFileContext remplace ce contexte par le contexte spécifié dans NewContext. Sinon, il insère NewContext dans la liste des contextes du fichier.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Si un contexte est déjà défini pour le fichier vers lequel FileObject pointe, FltSetFileContext retourne STATUS_FLT_CONTEXT_ALREADY_DEFINED et ne remplace pas le contexte existant ni n’incrémente le nombre de références. Si aucun contexte n’a déjà été défini, la routine insère le contexte spécifié dans NewContext dans la liste des contextes du fichier et incrémente le nombre de références.

[in] NewContext

Pointeur vers le nouveau contexte à définir pour le fichier. Ce paramètre est obligatoire et ne peut pas être NULL.

[out] OldContext

Pointeur vers une variable allouée à l’appelant qui reçoit l’adresse du contexte de fichier existant pour l’instance pointée par le paramètre Instance, s’il est déjà défini. Ce paramètre est facultatif et peut être NULL. Pour plus d’informations sur ce paramètre, consultez la section Remarques suivante.

Valeur retournée

La routine FltSetFileContext retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour Description
STATUS_FLT_CONTEXT_ALREADY_DEFINED Si FLT_SET_CONTEXT_KEEP_IF_EXISTS a été spécifié pour le paramètre Operation , ce code d’erreur indique qu’un contexte est déjà attaché au fichier.
STATUS_FLT_CONTEXT_ALREADY_LINKED Le contexte vers lequel pointe le paramètre NewContext est déjà lié à un objet . En d’autres termes, ce code d’erreur indique que NewContext est déjà utilisé en raison d’un appel antérieur réussi d’une routine FltSetXxxContext .
STATUS_FLT_DELETING_OBJECT Le instance spécifié dans le paramètre Instance est en cours de déclassé. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER Un paramètre non valide a été passé. Par exemple, le paramètre NewContext ne pointe pas vers un contexte de fichier valide ou une valeur non valide a été spécifiée pour le paramètre Operation . Il s’agit d’un code d’erreur.
STATUS_NOT_SUPPORTED Les contextes de fichier ne sont pas pris en charge pour ce fichier. Il s’agit d’un code d’erreur.

Remarques

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

Un pilote de minifiltre appelle FltSetFileContext pour définir ou remplacer son propre contexte de fichier sur un fichier. Un pilote minifilter ne peut attacher qu’un seul contexte par pilote minifilter instance au fichier.

FltSetFileContext ne peut pas être appelé sur un FileObject non ouvert. Par conséquent , FltSetFileContext ne peut pas être appelé à partir d’un rappel de précréation pour un fichier, car le fichier n’a pas été ouvert à ce stade. Toutefois, un pilote minifilter peut allouer et configurer le contexte de fichier dans le rappel de précréation, le transmettre au rappel post-création à l’aide du paramètre de contexte d’achèvement et définir le contexte de fichier sur le fichier correspondant à ce flux dans le rappel post-création.

Décompte de références

Si FltSetFileContext réussit :

  • Le nombre de références sur NewContext est incrémenté. Lorsque NewContext n’est plus nécessaire, le minifilter doit appeler FltReleaseContext pour décrémenter son nombre de références.

Sinon, si FltSetFileContext échoue :

  • Le nombre de références sur NewContext reste inchangé.
  • Si OldContext n’a pas la valeur NULL et ne pointe pas vers NULL_CONTEXT OldContext est un pointeur référencé vers le contexte actuellement associé au fichier. Le filtre appelant FltSetFileContext doit éventuellement appeler FltReleaseContext pour OldContext , ainsi que lorsque le pointeur de contexte n’est plus nécessaire.

Quel que soit le succès :

  • Le filtre appelant FltSetFileContext doit appeler FltReleaseContext pour décrémenter le nombre de références sur l’objet NewContext incrémenté par FltAllocateContext.

Pour plus d’informations, consultez Référencement de contextes.

Autres opérations contextuelles

Pour plus d’informations, consultez Définition de contextes et Publication de contextes :

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible et pris en charge à partir de Windows Vista.
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

FltAllocateContext

FltDeleteContext

FltDeleteFileContext

FltGetFileContext

FltReleaseContext

FltSupportsFileContexts

FltSupportsFileContextsEx