FltSetVolumeContext, fonction (fltkernel.h)
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 éléments suivants :
Drapeau | 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 ou incrémente le nombre de références. Si un contexte n’a pas déjà é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 être 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 de retour
FltSetVolumeContext 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 Opération, ce code d’erreur indique qu’un contexte est déjà attaché au volume. |
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 | Le volume 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 volume valide, ou une valeur non valide a été spécifiée pour Opération. 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 FltSetVolumeContext pour attacher un contexte à un volume, ou pour supprimer ou remplacer un contexte de volume existant. Un pilote minifilter ne peut attacher qu’un seul contexte à un volume.
Comptage 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 minifilter 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’est pas 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 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 FltSetVolumeContext doit appeler FltReleaseContext pour décrémenter le nombre de références sur l’objet NewContext 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 de volume, appelez FltGetVolumeContext.
Pour supprimer un contexte de volume, appelez FltDeleteVolumeContext 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 |