FsRtlRemovePerStreamContext, fonction (ntifs.h)

Article
10/04/2023

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 pour le flux de fichiers. Pour obtenir ce pointeur à partir d’un objet fichier, utilisez la macro FsRtlGetPerStreamContextPointer .

[in, optional] OwnerId

Utilisé pour identifier les informations de contexte comme appartenant à un pilote de filtre particulier.

[in, optional] InstanceId

Permet de rechercher un instance particulier d’un contexte par flux. S’il n’est pas fourni, tous les contextes appartenant au pilote de filtre sont supprimés et retournés.

Si ni OwnerId ni InstanceId ne sont fournis, tout contexte par flux associé est supprimé et retourné.

Valeur retournée

FsRtlRemovePerStreamContext retourne un pointeur vers le contexte par flux qui est 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 renvoie la valeur 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 par flux correspondante trouvée. S’il existe d’autres contextes correspondants par flux, le pilote de filtre doit appeler FsRtlRemovePerStreamContext autant de fois que nécessaire pour les supprimer tous.

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 fichier alors 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 fichier. FsRtlTeardownPerStreamContexts décrit 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 distribution IRP_MJ_CLOSE ou IRP_MJ_PNP. Non seulement un tel appel serait inutile, mais il pourrait é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 de la routine FreeCallback d’une structure de contexte par flux. En effet, 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 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é.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Correctif cumulatif windows 2000 SP4 ; Windows XP
Plateforme cible	Universal
En-tête	ntifs.h (include Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL