FsRtlRemovePerStreamContext, fonction (ntifs.h)

Article
12/21/2024

FsRtlRemovePerStreamContext supprime une structure de contexte par flux de la liste des contextes par flux associés à un flux de fichiers.

Syntaxe

PFSRTL_PER_STREAM_CONTEXT FsRtlRemovePerStreamContext(
  [in]           PFSRTL_ADVANCED_FCB_HEADER StreamContext,
  [in, optional] PVOID                      OwnerId,
  [in, optional] PVOID                      InstanceId
);

Paramètres

[in] StreamContext

Pointeur vers la structure FSRTL_ADVANCED_FCB_HEADER du flux de fichiers. Pour obtenir ce pointeur à partir d’un objet de fichier, utilisez la macro FsRtlGetPerStreamContextPointer.

[in, optional] OwnerId

Permet d’identifier les informations de contexte comme appartenant à un pilote de filtre particulier.

[in, optional] InstanceId

Utilisé pour rechercher une instance particulière d’un contexte par flux. S’il n’est pas fourni, l’un des contextes appartenant au pilote de filtre est supprimé et retourné.

Si ni l’id de propriétaire ni l’id d’instance n’est fourni, tout contexte associé par flux est supprimé et retourné.

Valeur de retour

FsRtlRemovePerStreamContext retourne un pointeur vers le contexte par flux supprimé. Si aucune correspondance n’est trouvée ou si le système de fichiers ne prend pas en charge les contextes de filtre, FsRtlRemovePerStreamContext retourne NULL.

Remarques

Un pilote de filtre de système de fichiers appelle FsRtlRemovePerStreamContext pour supprimer sa propre structure de contexte par flux de la liste des contextes par flux associés à un flux de fichiers.

FsRtlRemovePerStreamContext supprime uniquement la première structure de contexte correspondante par flux trouvée. S’il existe des contextes de correspondance supplémentaires par flux, le pilote de filtre doit appeler FsRtlRemovePerStreamContext autant de fois que nécessaire pour les supprimer.

Cette routine ne doit être utilisée que lorsqu’un pilote de filtre doit ignorer les informations de contexte qu’il a associées à un flux de fichiers pendant que le flux est toujours ouvert. Par exemple, un pilote de filtre peut appeler FsRtlRemovePerStreamContext dans les cas suivants :

Lorsqu’il reçoit une demande d’une application en mode utilisateur pour arrêter la journalisation des demandes d’E/S sur un volume particulier.
Lorsqu’il détecte qu’un fichier ou un répertoire a été renommé.

Lorsqu’un flux de fichiers est fermé, le système de fichiers est chargé de s’assurer que tous les contextes par flux associés à ce flux sont supprimés et libérés. Pour ce faire, le système de fichiers doit appeler FsRtlTeardownPerStreamContexts sur le bloc de contrôle de fichier (FCB) ou un autre objet de contexte de flux pour le flux de fichiers. FsRtlTeardownPerStreamContexts guide la liste FilterContexts, en supprimant chaque entrée et en appelant sa routine FreeCallback.

Par conséquent, un pilote de filtre de système de fichiers ne doit pas appeler FsRtlRemovePerStreamContext à partir d’une routine de répartition IRP_MJ_CLOSE ou IRP_MJ_PNP. Non seulement un tel appel serait-il inutile, mais il peut également interférer avec l’appel du système de fichiers à FsRtlTeardownPerStreamContexts.

Un pilote de filtre de système de fichiers ne doit pas appeler FsRtlRemovePerStreamContext à partir d’une structure de contexte par flux FreeCallback routine. Cela est dû au fait que le système de fichiers sous-jacent appelle la routine FreeCallback après avoir déjà supprimé la structure de contexte de la liste FilterContexts.

Pour initialiser une structure de contexte par flux, utilisez la macro FsRtlInitPerStreamContext.

Pour associer une structure de contexte par flux initialisée à un flux de fichiers, appelez FsRtlInsertPerStreamContext.

Pour récupérer une structure de contexte par flux de données associée à un flux de fichiers, appelez FsRtlLookupPerStreamContext.

FsRtlRemovePerStreamContext ne peut être utilisé que sur les systèmes de fichiers qui prennent en charge les contextes de filtre.

Pour plus d’informations, consultez suivi Per-Stream contexte dans un pilote de filtre de système de fichiers hérité.

Exigences

Exigence	Valeur
client minimum pris en charge	Correctif cumulatif windows 2000 SP4 ; Windows XP
plateforme cible	Universel
d’en-tête	ntifs.h (include Ntifs.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL