QUERY_FILE_LAYOUT_INPUT structure (ntifs.h)

The QUERY_FILE_LAYOUT_INPUT structure selects which file layout entries are returned from a FSCTL_QUERY_FILE_LAYOUT request.

Syntax

typedef struct _QUERY_FILE_LAYOUT_INPUT {
  union {
    ULONG FilterEntryCount;
    ULONG NumberOfPairs;
  } DUMMYUNIONNAME;
  ULONG                         Flags;
  QUERY_FILE_LAYOUT_FILTER_TYPE FilterType;
  ULONG                         Reserved;
  union {
    CLUSTER_RANGE        ClusterRanges[1];
    FILE_REFERENCE_RANGE FileReferenceRanges[1];
    STORAGE_RESERVE_ID   StorageReserveIds[1];
  } Filter;
} QUERY_FILE_LAYOUT_INPUT, *PQUERY_FILE_LAYOUT_INPUT;

Members

DUMMYUNIONNAME

DUMMYUNIONNAME.FilterEntryCount

The number of filter entries in the Filter array.

DUMMYUNIONNAME.NumberOfPairs

The original name of the field when there was only one type of filter. The union is simply to maintain code compatibility.

Flags

Indicates which file layout entries are included in the query results. Flags is set to a valid combination of the following values.

FilterType

Specifies a filtering method to restrict returned layout information. Can be one of following values.

Reserved

Reserved for system use.

Filter

An array of filter structures used to select specific layout information. These contain either cluster or file reference ranges. The array length is specified by the NumberOfPairs member. Each range must be distinct and cannot overlap with any other range.

This member is ignored if QUERY_FILE_LAYOUT_FILTER_TYPE_NONE is specified in FilterType.

Filter.ClusterRanges[1]

Specifies a set of cluster ranges to filter layout information. The range structure has the following format.

typedef struct _CLUSTER_RANGE {
    LARGE_INTEGER    StartingCluster;
    LARGE_INTEGER    ClusterCount;
} CLUSTER_RANGE, *PCLUSTER_RANGE;

Filter.FileReferenceRanges[1]

Specifies a set of file reference ranges to filter layout information. Available starting in Windows 10 version 1809. The range structure has the following format.

typedef struct _FILE_REFERENCE_RANGE {
    LARGE_INTEGER    StartingFileReference;
    LARGE_INTEGER    EndingReferenceNumber;
} FILE_REFERENCE_RANGE, *PFILE_REFERENCE_RANGE;

Filter.StorageReserveIds[1]

Specifies a set of storage reserve IDs to filter layout information. The associated enumeration has the following format.

typedef enum _STORAGE_RESERVE_ID {

    StorageReserveIdNone = 0,
    StorageReserveIdHard,
    StorageReserveIdSoft,
    StorageReserveIdUpdateScratch,

    StorageReserveIdMax

} STORAGE_RESERVE_ID, *PSTORAGE_RESERVE_ID;

Remarks

The QUERY_FILE_LAYOUT_RESTART flag is set on the first FSCTL_QUERY_FILE_LAYOUT request. If filter ranges are included in the request, they are cached when QUERY_FILE_LAYOUT_RESTART is set. Further requests will return layout file entries until the end of the volume or until filter ranges are exhausted.

If QUERY_FILE_LAYOUT_RESTART is set again for the same volume, the file layout position is reset to the beginning of the volume. Additionally, the filter ranges are re-cached and their evaluation order is reset to the first range.

The file layout entries are returned in the output buffer following a QUERY_FILE_LAYOUT_OUTPUT structure.

When FilterType is QUERY_FILE_LAYOUT_FILTER_TYPE_CLUSTERS, the ClusterRanges member of the Filter union is used for range filtering. Otherwise, if FilterType is QUERY_FILE_LAYOUT_FILTER_TYPE_FILEID, the FileReferenceRanges member is used for range filtering.

Requirements

See also

FSCTL_QUERY_FILE_LAYOUT

QUERY_FILE_LAYOUT_OUTPUT