structure FSRTL_ADVANCED_FCB_HEADER (ntifs.h)

Article
12/21/2024

La structure FSRTL_ADVANCED_FCB_HEADER contient des informations de contexte qu’un système de fichiers conserve sur un fichier.

Syntaxe

typedef struct _FSRTL_ADVANCED_FCB_HEADER {
  FSRTL_COMMON_FCB_HEADER          DUMMYSTRUCTNAME;
  PFAST_MUTEX                      FastMutex;
  LIST_ENTRY                       FilterContexts;
  EX_PUSH_LOCK                     PushLock;
  PVOID                            *FileContextSupportPointer;
  union {
    OPLOCK Oplock;
    PVOID  ReservedForRemote;
  };
  PVOID                            AePushLock;
  PVOID                            ReservedContextLegacy;
  ULONG                            BypassIoOpenCount;
  struct _FSRTL_PER_STREAM_CONTEXT *ReservedContext;
} FSRTL_ADVANCED_FCB_HEADER;

Membres

DUMMYSTRUCTNAME

Membre sans nom qui contient une structure de type FSRTL_COMMON_FCB_HEADER.

FastMutex

Pointeur vers un mutex rapide initialisé utilisé pour synchroniser l’accès aux membres suivants de DUMMYSTRUCTNAME:

AllocationSize
FileSize
ValidDataLength

S’il est présent, le membre PushLock est utilisé pour synchroniser l’accès au membre FilterContexts ; sinon, FastMutex est utilisé.

FilterContexts

Pointeur vers la tête d’une liste de toutes les structures de contexte associées au fichier. Les pilotes de filtre peuvent rechercher dans cette liste en appelant FsRtlLookupPerStreamContext et en le modifiant en appelant FsRtlInsertPerStreamContext et FsRtlRemovePerStreamContext.

PushLock

Verrou push utilisé pour synchroniser l’accès à la liste FilterContexts. Ce champ est disponible uniquement à partir de Windows Vista (autrement dit, si la version version champ bit de la structure FSRTL_COMMON_FCB_HEADER est supérieure ou égale à FSRTL_FCB_HEADER_V1).

FileContextSupportPointer

Pointeur vers un champ de pointeur utilisé par la bibliothèque d’exécution du système de fichiers (FSRTL) pour suivre les contextes de fichier. Si ce n’est pas NULL, ce membre doit être un pointeur vers une variable PVOID à l’intérieur d’une structure par fichier pour le système de fichiers qui a créé la structure. Si NULL, les contextes de fichier ne sont pas pris en charge. Ce membre est disponible uniquement à partir de Windows Vista (autrement dit, si la version version champ bit de la structure FSRTL_COMMON_FCB_HEADER est supérieure ou égale à FSRTL_FCB_HEADER_V1).

Oplock

Oplock pour le fichier ou le répertoire. Ce champ est disponible uniquement à partir de Windows 8 (autrement dit, si la version version champ bit de la structure FSRTL_COMMON_FCB_HEADER est supérieure ou égale à FSRTL_FCB_HEADER_V2).

ReservedForRemote

Si le système de fichiers est distant, ce champ est réservé. Il est disponible uniquement à partir de Windows 8 (autrement dit, si la version version champ bit de la structure FSRTL_COMMON_FCB_HEADER est supérieure ou égale à FSRTL_FCB_HEADER_V2).

AePushLock

Verrou push de développement automatique utilisé au lieu de pushLock pour synchroniser l’accès à la liste des contextes de flux. Pour plus d’informations, consultez Remarques.

AePushlock est disponible à partir de Windows 10, version 20H2 (autrement dit, si le champ de bits Version de la structure FSRTL_COMMON_FCB_HEADER est supérieur ou égal à FSRTL_FCB_HEADER_V3), et doit être initialisé en appelant FsRtlSetupAdvancedHeaderEx2.

ReservedContextLegacy

Ce champ est réservé à l’utilisation du système. Elle est utilisée uniquement dans Windows 8.1 via Windows 10, version 1803 (si le champ de bits version de la structure FSRTL_COMMON_FCB_HEADER est supérieur ou égal à FSRTL_FCB_HEADER_V3).

BypassIoOpenCount

Suit le nombre de handles actuellement ouverts avec BypassIO activé sur ce flux.

Ce champ est disponible à partir de Windows 11 (autrement dit, si la version version champ bit de la structure FSRTL_COMMON_FCB_HEADER est supérieure ou égale à FSRTL_FCB_HEADER_V4).

ReservedContext

Réservé à l’utilisation du système.

Ce champ est disponible à partir de Windows 11, version 22H2 (autrement dit, si la version version champ bit de la structure FSRTL_COMMON_FCB_HEADER est supérieure ou égale à FSRTL_FCB_HEADER_V5).

Remarques

La structure FSRTL_ADVANCED_FCB_HEADER est un sur-ensemble de la structure FSRTL_COMMON_FCB_HEADER. Les systèmes de fichiers (y compris les pilotes de filtre hérité et de mini-filtre, le cas échéant) doivent utiliser la structure FSRTL_ADVANCED_FCB_HEADER.

Les systèmes de fichiers doivent utiliser l’une des macros suivantes pour initialiser la structure FSRTL_ADVANCED_FCB_HEADER :

FsRtlSetupAdvancedHeader
FsRtlSetupAdvancedHeaderEx
FsRtlSetupAdvancedHeaderEx2, disponible à partir de Windows 10, version 20H2.

Les indicateurs suivants sont définis par ces macros.

Drapeau	Signification
FSRTL_FLAG_ADVANCED_HEADER	Défini dans les indicateurs membre de la structure FSRTL_COMMON_FCB_HEADER, cet indicateur indique la prise en charge du pilote du système de fichiers pour les structures FSRTL_ADVANCED_FCB_HEADER. Cet indicateur ne doit pas être modifié.
FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS	Défini dans le membre Flags2 de FSRTL_COMMON_FCB_HEADER, cet indicateur indique la prise en charge des contextes de pilote de filtre. Cet indicateur ne peut être effacé que pour la pagination des fichiers (voir les informations après le tableau).

Les systèmes de fichiers doivent définir le FsContext membre de chaque objet de fichier pour qu’il pointe vers une structure FSRTL_ADVANCED_FCB_HEADER. Cette structure peut être incorporée à l’intérieur d’une structure d’objet de contexte spécifique à un flux de système de fichiers (le reste de la structure est spécifique au système de fichiers). En règle générale, cette structure est un bloc de contrôle de fichier (FCB). Toutefois, sur certains systèmes de fichiers qui prennent en charge plusieurs flux de données, tels que NTFS, il s’agit d’un bloc de contrôle de flux (SCB). Notez que les bases de données et les SBS pour toutes les classes de requêtes ouvertes, y compris les demandes d’ouverture de volume, doivent inclure cette structure.

Si le fichier est un fichier de pagination, la structure FSRTL_ADVANCED_FCB_HEADER doit être allouée à partir d’un pool non paginé. Sinon, il peut être alloué à partir d’un pool paginé ou non paginé.

Tous les systèmes de fichiers Microsoft désactivent la prise en charge du contexte de flux pour la pagination des fichiers en désactivant l’indicateur FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS dans le membre Flags2 de FSRTL_COMMON_FCB_HEADER après avoir appelé FsRtlSetupAdvancedHeader. (Consultez la fonction FatCreateFcb dans Strucsup.c pour l’exemple FASTFAT WDK.) Vous êtes fortement encouragé à faire de même dans votre système de fichiers ou systèmes afin que le système d’exploitation se comporte de manière cohérente dans tous les systèmes de fichiers.

Verrouillages push de développement automatique

Les verrous push de développement automatique ont été introduits dans Windows 10, version 20H2. Lorsque les verrous de Filter Manager ont été conçus à l’origine, les grands systèmes multiprocesseurs étaient très rares et la RAM était précieuse. Avec ces systèmes désormais courants et ram non aussi limités, les verrous push de développement automatique offrent un compromis bénéfique entre la consommation de mémoire et la vitesse.

Un verrou push de développement automatique peut passer automatiquement d’un verrou push non prenant en compte le cache standard à un verrou push prenant en compte le cache lorsqu’il détecte qu’il est soumis à une contention élevée de cache en raison d’un grand nombre d’acquisitions partagées simultanées. Le verrou push de développement automatique est plus grand qu’un verrou push normal lorsqu’il n’est pas développé, mais pas aussi grand qu’un verrou push prenant en charge le cache. Ce type de verrou push est plus performant sur les systèmes multiprocesseurs.