Fonction FltSetStreamContext (fltkernel.h)

Article
02/26/2024

La routine FltSetStreamContext définit un contexte pour un flux de fichiers.

Syntaxe

NTSTATUS FLTAPI FltSetStreamContext(
  [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 de instance opaque pour le pilote minifiltre instance dont le contexte doit être inséré, supprimé ou remplacé dans la liste des contextes attachés au flux de fichiers.

[in] FileObject

Pointeur vers un objet de fichier pour le flux de fichiers.

[in] Operation

Indicateur spécifiant les détails de l’opération à effectuer. Ce paramètre doit être l’un des suivants :

Indicateur	Signification
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Si un contexte est déjà défini pour Instance, FltSetStreamContext le remplace par le contexte spécifié dans NewContext. Sinon, il insère NewContext dans la liste des contextes du flux de fichiers.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Si un contexte est déjà défini pour cette instance, FltSetStreamContext retourne STATUS_FLT_CONTEXT_ALREADY_DEFINED et ne remplace pas le contexte existant ni n’incrémente le nombre de références. Si un contexte n’a pas encore été défini, la routine insère NewContext dans la liste des contextes du flux de fichiers et incrémente le nombre de références.

[in] NewContext

Pointeur vers le nouveau contexte à définir pour le flux de fichiers. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[out] OldContext

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse du contexte de flux existant pour le paramètre Instance , le cas échéant. 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 FltSetStreamContext 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 Operation, ce code d’erreur indique qu’un contexte de flux est déjà attaché au flux de fichiers.
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 de contexteFltSetXxx.
STATUS_FLT_DELETING_OBJECT	Le instance spécifié dans le paramètre Instance est en cours de arraché. 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 flux 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	Le système de fichiers ne prend pas en charge les contextes par flux pour ce flux de fichiers. 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 FltSetStreamContext pour attacher un contexte de flux à un flux de fichiers ou pour supprimer ou remplacer un contexte de flux existant. Un pilote de minifiltre peut attacher un contexte par pilote de minifiltre instance au flux de fichiers.

FltSetStreamContext ne peut pas être appelé sur un Objet FileObject non ouvert. Par conséquent, il ne peut pas être appelé à partir d’un rappel préalable à la création d’un flux, car le flux n’a pas été ouvert à ce stade. Toutefois, un pilote de minifiltre peut allouer et configurer le contexte de flux 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 flux sur le flux dans le rappel post-création.

Décompte de références

Si FltSetStreamContext réussit :

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

Sinon, si FltSetStreamContext é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 flux. Le filtre appelant FltSetStreamContext doit également appeler FltReleaseContext pour OldContext lorsque le pointeur de contexte n’est plus nécessaire.

Quelle que soit la réussite :

Le filtre appelant FltSetStreamContext 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 de contexte

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

Pour déterminer si les contextes de flux sont pris en charge pour un fichier donné, appelez FltSupportsStreamContexts
Pour allouer un nouveau contexte, appelez FltAllocateContext.
Pour obtenir un contexte de flux, appelez FltGetStreamContext.
Pour supprimer un contexte de flux, appelez FltDeleteStreamContext ou FltDeleteContext.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible et pris en charge dans microsoft Windows 2000 Update Rollup 1 pour les systèmes d’exploitation SP4, Windows XP SP2, Windows Server 2003 SP1 et versions ultérieures.
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h)
Bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL