FltSetInstanceContext, fonction (fltkernel.h)

Article
02/06/2025

FltSetInstanceContext définit un contexte pour une instance de pilote minifilter.

Syntaxe

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

Paramètres

[in] Instance

Pointeur d’instance opaque pour l’instance.

[in] Operation

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

Drapeau	Signification
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Si un contexte est déjà défini pour l’instance vers laquelle pointe le paramètre Instance, FltSetInstanceContext remplace ce contexte par le contexte spécifié dans NewContext. Dans le cas contraire, elle définit NewContext comme contexte pour instance.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Si un contexte est déjà défini pour cette Instance, FltSetInstanceContext retourne STATUS_FLT_CONTEXT_ALREADY_DEFINED et ne remplace pas le contexte existant ou incrémente le nombre de références. Si un contexte n’est pas déjà défini, la routine définit NewContext comme contexte pour Instance et incrémente le nombre de références.

[in] NewContext

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

[out] OldContext

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse du contexte d’instance existant, si elle est déjà définie. 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

FltSetInstanceContext retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’une des valeurs suivantes :

Retourner le code	Description
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Si FLT_SET_CONTEXT_KEEP_IF_EXISTS a été spécifié pour le paramètre opération de, ce code d’erreur indique qu’un contexte est déjà attaché à l’instance. Un seul contexte peut être attaché à une instance.
STATUS_FLT_CONTEXT_ALREADY_LINKED	Le contexte pointé par 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 d’une routine FltSetXxxContext.
STATUS_FLT_DELETING_OBJECT	L’instance spécifiée dans le paramètre Instance est détruite. 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.

Remarques

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

Un pilote minifilter appelle FltSetInstanceContext pour attacher un contexte d’instance à une instance de pilote minifilter appartenant à l’appelant ou pour supprimer ou remplacer un contexte d’instance existant. Un pilote minifilter ne peut attacher qu’un seul contexte à une instance.

Comptage de références

Si FltSetInstanceContext réussit :

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

Sinon, si FltSetInstanceContext é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é à l’instance. Le filtre appelant FltSetInstanceContext 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 FltSetInstanceContext 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 allouer un nouveau contexte, appelez FltAllocateContext.
Pour obtenir un contexte d’instance, appelez FltGetInstanceContext.
Pour supprimer un contexte d’instance, appelez FltDeleteInstanceContext 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 du système d’exploitation.
plateforme cible	Universel
d’en-tête	fltkernel.h (include Fltkernel.h)
bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL