Fonction FltSetInstanceContext (fltkernel.h)

  • Article

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

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 de instance opaque pour le 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 :

Indicateur Signification
FLT_SET_CONTEXT_REPLACE_IF_EXISTS Si un contexte est déjà défini pour le instance vers lequel pointe le paramètre Instance, FltSetInstanceContext remplace ce contexte par le contexte spécifié dans NewContext. Sinon, il 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 ni n’incrémente le nombre de références. Si aucun contexte n’est 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 le instance. 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 instance existant, 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

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

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 instance. Un seul contexte peut être attaché à un instance.
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.

Remarques

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

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

Décompte 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’a pas la valeur 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 finalement 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é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 dans microsoft Windows 2000 Update Rollup 1 pour SP4, Windows XP SP2, Windows Server 2003 SP1 et versions ultérieures du système d’exploitation.
Plateforme cible Universal
En-tête fltkernel.h (inclure Fltkernel.h)
Bibliothèque FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Voir aussi

FltAllocateContext

FltDeleteContext

FltDeleteInstanceContext

FltGetInstanceContext

FltReleaseContext