FSRTL_ADVANCED_FCB_HEADER structure

The FSRTL_ADVANCED_FCB_HEADER structure contains context information that a file system maintains about a file.

Syntax


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;
  };
} FSRTL_ADVANCED_FCB_HEADER, *PFSRTL_ADVANCED_FCB_HEADER;

Members

DUMMYSTRUCTNAME

An unnamed member that contains a structure of type FSRTL_COMMON_FCB_HEADER.

FastMutex

A pointer to an initialized fast mutex that is used to synchronize access to the following members of DUMMYSTRUCTNAME:

  • AllocationSize

  • FileSize

  • ValidDataLength

If present, the PushLock member is used to synchronize access to the FilterContexts member; otherwise, FastMutex is used.

FilterContexts

A pointer to the head of a list of all context structures that are associated with the file. Filter drivers can search this list by calling FsRtlLookupPerStreamContext and modify it by calling FsRtlInsertPerStreamContext and FsRtlRemovePerStreamContext.

PushLock

A push lock used to synchronize access to the FilterContexts list. This member is only available starting with Windows Vista (that is, if the Version bit-field of the FSRTL_COMMON_FCB_HEADER structure is greater than or equal to FSRTL_FCB_HEADER_V1).

FileContextSupportPointer

A pointer to a pointer field used by the file system runtime library (FSRTL) package to track file contexts. If not NULL, this member must be a pointer to a PVOID variable inside a per-file structure for the file system that created the structure. If NULL, file contexts are not supported. This member is only available starting with Windows Vista (that is, if the Version bit-field of the FSRTL_COMMON_FCB_HEADER structure is greater than or equal to FSRTL_FCB_HEADER_V1).

Oplock

The oplock for the file or directory. This member is only available starting with Windows 8 (that is, if the Version bit-field of the FSRTL_COMMON_FCB_HEADER structure is greater than or equal to FSRTL_FCB_HEADER_V2).

ReservedForRemote

If the file system is remote, this field is reserved. This member is only available starting with Windows 8 (that is, if the Version bit-field of the FSRTL_COMMON_FCB_HEADER structure is greater than or equal to FSRTL_FCB_HEADER_V2).

Remarks

The FSRTL_ADVANCED_FCB_HEADER structure is a superset of the FSRTL_COMMON_FCB_HEADER structure. File systems (including legacy filter and minifilter drivers, when applicable) must use the FSRTL_ADVANCED_FCB_HEADER structure.

File systems must use the FsRtlSetupAdvancedHeader macro or the FsRtlSetupAdvancedHeaderEx macro to initialize an FSRTL_ADVANCED_FCB_HEADER structure.

The following flags are set by the FsRtlSetupAdvancedHeader and FsRtlSetupAdvancedHeaderEx macros.

FlagMeaning

FSRTL_FLAG_ADVANCED_HEADER

Set in the Flags member of the FSRTL_COMMON_FCB_HEADER structure, this flag indicates file system driver support for FSRTL_ADVANCED_FCB_HEADER structures. This flag should not be modified.

FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS

Set in the Flags2 member of FSRTL_COMMON_FCB_HEADER, this flag indicates support for filter driver contexts. This flag can only be cleared for paging files (see information after the table).

FSRTL_FCB_HEADER_V1

Set in the Version member of FSRTL_COMMON_FCB_HEADER, this value indicates support for the PushLock and FilterContextPointer members. This flag should not be modified.

FSRTL_FCB_HEADER_V2

Set in the Version member of FSRTL_COMMON_FCB_HEADER, this value indicates support for the PushLock, FilterContextPointer, Oplock, and ReservedForRemote members. This flag should not be modified.

 

File systems must set the FsContext member of every file object to point to an FSRTL_ADVANCED_FCB_HEADER structure. This structure can be embedded inside of a context object structure that is specific to a file-system stream (the remainder of the structure is file-system–specific). Usually, this structure is a file control block (FCB). However, on some file systems that support multiple data streams, such as NTFS, it is a stream control block (SCB). Note that FCBs and SCBs for all classes of open requests, including volume open requests, must include this structure.

If the file is a paging file, the FSRTL_ADVANCED_FCB_HEADER structure must be allocated from a nonpaged pool. Otherwise, it can be allocated from a paged or nonpaged pool.

All Microsoft file systems disable stream context support for paging files by clearing the FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS flag in the Flags2 member of FSRTL_COMMON_FCB_HEADER after they call FsRtlSetupAdvancedHeader. (See the FatCreateFcb function in Strucsup.c for the FASTFAT WDK sample.) You are strongly encouraged to do the same in your file system or systems so that the operating system will behave in a consistent manner across all file systems.

Requirements

Header

Ntifs.h (include Ntifs.h or Fltkernel.h)

See also

FSRTL_COMMON_FCB_HEADER
FSRTL_PER_STREAM_CONTEXT
FsRtlInsertPerStreamContext
FsRtlLookupPerStreamContext
FsRtlRemovePerStreamContext
FsRtlSetupAdvancedHeader
FsRtlSetupAdvancedHeaderEx
FsRtlTeardownPerStreamContexts

 

 

Send comments about this topic to Microsoft

Show: