structure FSRTL_PER_FILE_CONTEXT (ntifs.h)

Article
12/22/2024

Un pilote de filtre de système de fichiers hérité peut utiliser une structure de FSRTL_PER_FILE_CONTEXT pour associer des informations de contexte spécifiques au pilote à un fichier ouvert.

Syntaxe

typedef struct _FSRTL_PER_FILE_CONTEXT {
  LIST_ENTRY     Links;
  PVOID          OwnerId;
  PVOID          InstanceId;
  PFREE_FUNCTION FreeCallback;
} FSRTL_PER_FILE_CONTEXT, *PFSRTL_PER_FILE_CONTEXT;

Membres

Links

Lien pour cette structure dans la liste de toutes les structures de contexte par fichier associées au même fichier. FsRtlInsertPerFileContext insère ce membre dans la liste de toutes les structures de contexte par fichier pour un fichier.

OwnerId

Pointeur vers une mémoire tampon allouée par un pilote de filtre qui identifie de manière unique le propriétaire de la structure de contexte par fichier. Le format de cette variable est spécifique au pilote de filtre. Les pilotes de filtre doivent définir ce membre sur une valeur NULL non.

InstanceId

Pointeur vers une mémoire tampon allouée par un pilote de filtre qui peut être utilisé pour distinguer les structures de contexte par fichier créées par le même pilote de filtre. Le format de cette variable est spécifique au pilote de filtre. Les pilotes de filtre peuvent définir ce membre sur NULL.

FreeCallback

Pointeur vers une routine de rappel qui libère la structure de contexte par fichier. Les pilotes de filtre doivent définir ce membre sur une valeur NULL non.

Remarques

Pour associer des informations de contexte à un fichier, un pilote de filtre hérité alloue d’abord une structure de FSRTL_PER_FILE_CONTEXT et l’initialise à l’aide de FsRtlInsertPerFileContext. Le pilote utilise ensuite FsRtlInsertPerFileContext pour associer cet objet FSRTL_PER_FILE_CONTEXT au fichier. Lorsque le système supprime l’objet de contexte de fichier d’un fichier, il appelle FsRtlTeardownPerFileContexts qui appelle la routine FreeCallback spécifiée dans l’objet FSRTL_PER_FILE_CONTEXT. Ce rappel doit libérer l’objet de contexte spécifique au pilote.

Les enregistreurs de filtres doivent choisir un OwnerID valeur qui est à la fois significative et pratique, telle que l’adresse d’un objet de pilote ou d’un objet de périphérique.

Les enregistreurs de filtres doivent choisir une valeur InstanceID qui est à la fois significative et pratique, telle que l’adresse de l’objet de contexte de fichier pour le fichier. Utilisez la macro FsRtlGetPerFileContextPointer pour récupérer cette adresse à partir d’un objet de fichier.

La structure FSRTL_PER_FILE_CONTEXT peut être utilisée as-isou incorporée dans une structure de contexte par fichier définie par pilote.

La structure FSRTL_PER_FILE_CONTEXT peut être allouée à partir d’un pool paginé ou non paginé.

La macro FsRtlInitPerFileContext initialise une structure FSRTL_PER_FILE_CONTEXT.

Paramètres

FileContext

FSRTL_PER_FILE_CONTEXT

Objet FSRTL_PER_FILE_CONTEXT à initialiser.

OwnerId

PVOID

Pointeur vers une variable allouée par le pilote de filtre qui identifie de manière unique le propriétaire de la structure de contexte par fichier. Le format est spécifique au pilote de filtre. Ce paramètre doit avoir une valeur NULL non.

InstanceId

PVOID

freeCallback

PFREE_FUNCTION

Pointeur vers une routine de rappel qui libère la structure de contexte par fichier.

Valeur de retour

VOID

Aucun.

Cette macro doit être utilisée avant d’appeler FsRtlInsertPerFileContext.

Les enregistreurs de filtres doivent choisir un OwnerID valeur qui est à la fois significative et pratique, telle que l’adresse d’un objet de pilote ou d’un objet de périphérique.

Les enregistreurs de filtres doivent utiliser une valeur InstanceID qui est à la fois significative et pratique, telle que l’adresse de l’objet de contexte de fichier pour le fichier. Utilisez la macro FsRtlGetPerFileContextPointer pour récupérer cette adresse à partir d’un objet de fichier.

Pour plus d’informations sur l’utilisation et la création d’objets de contexte, consultez Tracking Per-File Context in a Legacy File System Filter Driver.