Fonction FltSetFileContext (fltkernel.h)
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 :
Pour allouer un nouveau contexte, appelez FltAllocateContext.
Pour obtenir un contexte de fichier, appelez FltGetFileContext.
Pour supprimer un contexte de fichier, appelez FltDeleteFileContext ou FltDeleteContext.
Pour déterminer si les contextes de fichier sont pris en charge pour un fichier donné, appelez FltSupportsFileContexts ou FltSupportsFileContextsEx.
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 |