FltSetStreamHandleContext, fonction (fltkernel.h)

Article
02/06/2025

La routine FltSetStreamHandleContext définit un contexte pour un handle de flux.

Syntaxe

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

Paramètres

[in] Instance

Pointeur d’instance opaque pour l’instance de pilote minifilter dont le contexte doit être inséré dans, supprimé ou remplacé dans la liste des contextes attachés au handle de flux.

[in] FileObject

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

[in] Operation

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

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

[in] NewContext

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

[out, optional] OldContext

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse du contexte de handle de flux existant pour le paramètre Instance, si un paramètre 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 de retour

La routine FltSetStreamHandleContext retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’un des codes d’erreur suivants :

Retourner le code	Description
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Si FLT_SET_CONTEXT_KEEP_IF_EXISTS a été spécifié pour Opération, ce code d’erreur indique qu’un contexte est déjà attaché au handle de flux.
STATUS_FLT_CONTEXT_ALREADY_LINKED	Contexte auquel NewContext points 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 d’un FltSetXxxContext routine.
STATUS_FLT_DELETING_OBJECT	Le d’instance spécifié est détruit. 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 handle de flux valide, ou une valeur non valide a été spécifiée pour Opération.
STATUS_NOT_SUPPORTED	Une situation non prise en charge s’est produite, comme le système de fichiers ne prend pas en charge les contextes par flux pour ce flux de fichiers, ou l’appelant a fourni une valeur NULL FileObject.

Remarques

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

Le FltSetStreamHandleContext routine ajoute, supprime ou remplace un contexte pour une instance de pilote minifilter sur un handle de flux. Un pilote minifilter peut attacher un contexte par instance de pilote minifilter au handle de flux.

FltSetStreamHandleContext ne peut pas être appelé sur un FileObjectnon ouvert. Par conséquent, FltSetStreamHandleContext ne peut pas être appelée à partir d’un rappel prédéfini pour un flux, car le flux n’a pas été ouvert à ce stade. Toutefois, un minifilter peut allouer et configurer le contexte de handle 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 handle de flux sur le flux dans le rappel post-création.

Comptage de références

Si FltSetStreamHandleContext 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 FltSetStreamHandleContext échoue :

Le nombre de références sur NewContext reste inchangé.
Si oldContext n’est pas NULL et ne pointe pas vers NULL_CONTEXT, OldContext est un pointeur référencé vers le contexte actuellement associé au handle de flux. Le filtre appelant FltSetStreamHandleContext doit 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 FltSetStreamHandleContext 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érencer des contextes.

Autres opérations de contexte

Pour plus d’informations, consultez Définition de contexteset publication de contextes:

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

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible et pris en charge dans le correctif cumulatif 1 de Microsoft Windows 2000 pour SP4, Windows XP SP2, Windows Server 2003 SP1 et versions ultérieures.
plateforme cible	Universel
d’en-tête	fltkernel.h (include Fltkernel.h)
bibliothèque	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL