structure FSRTL_ADVANCED_FCB_HEADER (ntifs.h)

Article
04/23/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 le début 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 la 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 le champ bit Version de la structure FSRTL_COMMON_FCB_HEADER est supérieur ou égal à FSRTL_FCB_HEADER_V1).

FileContextSupportPointer

Pointeur vers un champ de pointeur utilisé par la bibliothèque de runtime de système de fichiers (FSRTL) pour suivre les contextes de fichiers. S’il 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 la valeur est NULL, les contextes de fichiers ne sont pas pris en charge. Ce membre est disponible uniquement à partir de Windows Vista (autrement dit, si le champ bit Version de la structure FSRTL_COMMON_FCB_HEADER est supérieur ou égal à 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 le champ bit Version de la structure FSRTL_COMMON_FCB_HEADER est supérieur ou égal à 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 le champ bit Version de la structure FSRTL_COMMON_FCB_HEADER est supérieur ou égal à 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 bit 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. Il est utilisé uniquement dans Windows 8.1 à Windows 10 version 1803 (si le champ bit 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 le champ bit Version de la structure FSRTL_COMMON_FCB_HEADER est supérieur ou égal à FSRTL_FCB_HEADER_V4).

ReservedContext

Réservé pour le système.

Ce champ est disponible à partir de Windows 11, version 22H2 (autrement dit, si le champ bit Version de la structure FSRTL_COMMON_FCB_HEADER est supérieur ou égal à 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 et de minifiltre hérités, 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.

Indicateur	Signification
FSRTL_FLAG_ADVANCED_HEADER	Défini dans le membre Indicateurs de la structure FSRTL_COMMON_FCB_HEADER , cet indicateur indique la prise en charge des pilotes de 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 membre FsContext 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 CCF et les SBS pour toutes les classes de requêtes ouvertes, y compris les demandes ouvertes en 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 supprimant 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.) Nous vous encourageons vivement à faire de même dans votre ou vos systèmes de fichiers afin que le système d’exploitation se comporte de manière cohérente sur tous les systèmes de fichiers.

Développer automatiquement les verrous push

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

Un verrou push de développement automatique peut automatiquement passer d’un verrou push normal non prenant en charge le cache à un verrou push prenant en charge le cache lorsqu’il détecte qu’il est soumis à une contention de cache élevée en raison d’un grand nombre d’acquéreurs partagés simultanés. 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.