Fonction FltSetVolumeContext (fltkernel.h)

  • Article

FltSetVolumeContext définit un contexte pour un volume.

Syntaxe

NTSTATUS FLTAPI FltSetVolumeContext(
  [in]            PFLT_VOLUME               Volume,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Paramètres

[in] Volume

Pointeur de volume opaque pour le volume.

[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 Volume, FltSetVolumeContext le remplace par NewContext>. Sinon, il insère NewContext dans la liste des contextes du volume.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Si un contexte est déjà défini pour ce volume, FltSetVolumeContext retourne STATUS_FLT_CONTEXT_ALREADY_DEFINED et ne remplace pas le contexte existant ni 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 volume et incrémente le nombre de références.

[in] NewContext

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

[out, optional] OldContext

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse du contexte de volume existant pour Volume. 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

FltSetVolumeContext 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 est déjà attaché au volume.
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 volume spécifié est en cours de démolir. 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 volume valide ou une valeur non valide a été spécifiée pour 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 FltSetVolumeContext pour attacher un contexte à un volume, ou pour supprimer ou remplacer un contexte de volume existant. Un pilote de minifiltre ne peut attacher qu’un seul contexte à un volume.

Décompte de références

Si FltSetVolumeContext 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 FltSetVolumeContext é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 volume. Le filtre appelant FltSetVolumeContext 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 FltSetVolumeContext 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 :

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

Voir aussi

FltAllocateContext

FltDeleteContext

FltDeleteVolumeContext

FltGetVolumeContext

FltReleaseContext