Fonction FltSetTransactionContext (fltkernel.h)

Article
08/07/2023

La routine FltSetTransactionContext définit un contexte sur une transaction.

Syntaxe

NTSTATUS FLTAPI FltSetTransactionContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PKTRANSACTION             Transaction,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Paramètres

[in] Instance

Pointeur instance opaque pour l’appelant.

[in] Transaction

Pointeur de transaction opaque pour la transaction sur laquelle le contexte est défini.

[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 :

Indicateur	Signification
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Si un contexte est déjà défini pour la transaction pointée vers le paramètre Transaction , FltSetTransactionContext le remplace par le contexte vers lequel pointe le paramètre NewContext . Sinon, il définit le contexte vers lequel pointe le paramètre NewContext comme contexte de la transaction pointée par le paramètre Transaction .
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Si un contexte est déjà défini pour la transaction pointée vers le paramètre Transaction , FltSetTransactionContext 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, cette routine définit le contexte vers lequel pointe le paramètre NewContext en tant que contexte de transaction pointé par le paramètre Transaction et incrémente le nombre de références.

Indicateur

Signification

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Si un contexte est déjà défini pour la transaction pointée vers le paramètre Transaction , FltSetTransactionContext le remplace par le contexte vers lequel pointe le paramètre NewContext . Sinon, il définit le contexte vers lequel pointe le paramètre NewContext comme contexte de la transaction pointée par le paramètre Transaction .

FLT_SET_CONTEXT_KEEP_IF_EXISTS

Si un contexte est déjà défini pour la transaction pointée vers le paramètre Transaction , FltSetTransactionContext 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, cette routine définit le contexte vers lequel pointe le paramètre NewContext en tant que contexte de transaction pointé par le paramètre Transaction et incrémente le nombre de références.

[in] NewContext

Pointeur vers le nouveau contexte à définir pour la transaction. 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 transaction 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

FltSetTransactionContext 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é à la transaction. Un seul contexte peut être attaché à une transaction pour un pilote minifilter donné.
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 transaction 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 de minifiltre appelle FltSetTransactionContext pour attacher un contexte à une transaction ou pour supprimer ou remplacer un contexte de transaction existant. Un pilote minifilter ne peut attacher qu’un seul contexte à une transaction donnée.

Décompte de références

Si FltSetTransactionContext 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 FltSetTransactionContext é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é à la transaction. Le filtre appelant FltSetTransactionContext doit également appeler FltReleaseContext pour OldContext lorsque le pointeur de contexte n’est plus nécessaire.

Quel que soit le succès :

Le filtre appelant FltSetTransactionContext 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 transaction, appelez FltGetTransactionContext.

Pour supprimer un contexte de transaction, appelez FltDeleteTransactionContext ou FltDeleteContext.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible et pris en charge dans Windows Vista et les systèmes d’exploitation ultérieurs.
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h)
Bibliothèque	FltMgr.lib
DLL	FltMgr.sys
IRQL	<= APC_LEVEL.