структура USN_RECORD_V4 (winioctl.h)

Статья
03/08/2023

Содержит сведения для записи журнала изменений версии 4.0 для последовательного номера обновления (USN). Записи версий 2.0 и 3.0 определяются USN_RECORD_V2 (также называемые USN_RECORD) и USN_RECORD_V3 структурами соответственно.

Синтаксис

typedef struct {
  USN_RECORD_COMMON_HEADER Header;
  FILE_ID_128              FileReferenceNumber;
  FILE_ID_128              ParentFileReferenceNumber;
  USN                      Usn;
  DWORD                    Reason;
  DWORD                    SourceInfo;
  DWORD                    RemainingExtents;
  WORD                     NumberOfExtents;
  WORD                     ExtentSize;
  USN_RECORD_EXTENT        Extents[1];
} USN_RECORD_V4, *PUSN_RECORD_V4;

Члены

Header

Структура USN_RECORD_COMMON_HEADER , описывающая длину записи, основную версию и дополнительную версию записи.

FileReferenceNumber

128-разрядный порядковый номер файла или каталога, для которых изменяется эта запись.

Это значение является произвольно назначенным значением, которое связывает запись журнала с файлом.

ParentFileReferenceNumber

128-разрядный порядковый номер каталога, в котором находится файл или каталог, связанный с этой записью.

Это значение является произвольно назначенным значением, которое связывает запись журнала с родительским каталогом.

Usn

UsN этой записи.

Reason

Флаги, определяющие причины изменений, накопленных в этом файле или записи журнала каталога с момента открытия файла или каталога.

При закрытии файла или каталога создается окончательная запись USN с установленным флагом USN_REASON_CLOSE . Следующее изменение (например, после следующей операции открытия или удаления) запускает новую запись с новым набором флагов причины.

Операция переименования или перемещения создает две записи USN: одна из них записывает старый родительский каталог для элемента, а другая — новый родительский.

В следующей таблице указаны возможные флаги.

Примечание Неиспользуемые биты зарезервированы.

Значение	Значение
USN_REASON_BASIC_INFO_CHANGE 0x00008000	Пользователь изменил один или несколько атрибутов файла или каталога (например, атрибут только для чтения, скрытый, системный, архивный или разреженный атрибут) или одну или несколько меток времени.
USN_REASON_CLOSE 0x80000000	Файл или каталог закрыт.
USN_REASON_COMPRESSION_CHANGE 0x00020000	Состояние сжатия файла или каталога изменяется с или на сжатое.
USN_REASON_DATA_EXTEND 0x00000002	Файл или каталог расширяется (добавляется в ).
USN_REASON_DATA_OVERWRITE 0x00000001	Данные в файле или каталоге перезаписываются.
USN_REASON_DATA_TRUNCATION 0x00000004	Файл или каталог усечен.
USN_REASON_EA_CHANGE 0x00000400	Пользователь внес изменения в расширенные атрибуты файла или каталога. Эти атрибуты файловой системы NTFS недоступны для приложений windows.
USN_REASON_ENCRYPTION_CHANGE 0x00040000	Файл или каталог шифруются или расшифровываются.
USN_REASON_FILE_CREATE 0x00000100	Файл или каталог создается в первый раз.
USN_REASON_FILE_DELETE 0x00000200	Файл или каталог будут удалены.
USN_REASON_HARD_LINK_CHANGE 0x00010000	Жесткая ссылка файловой системы NTFS добавляется в файл или каталог или удаляется из него. Жесткая ссылка файловой системы NTFS, аналогичная жесткой ссылке POSIX, является одной из нескольких записей каталога, которые видят один и тот же файл или каталог.
USN_REASON_INDEXABLE_CHANGE 0x00004000	Пользователь изменяет атрибут FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . То есть пользователь изменяет файл или каталог с того, где содержимое может быть проиндексировано, на тот, где содержимое не может быть проиндексировано, или наоборот. Индексирование контента позволяет быстро искать данные, создавая базу данных выбранного содержимого.
USN_REASON_INTEGRITY_CHANGE 0x00800000	Пользователь изменил состояние атрибута FILE_ATTRIBUTE_INTEGRITY_STREAM для заданного потока. В файловой системе ReFS потоки целостности поддерживают контрольную сумму всех данных для этого потока, чтобы содержимое файла можно было проверить во время операций чтения или записи.
USN_REASON_NAMED_DATA_EXTEND 0x00000020	Один или несколько именованных потоков данных для файла расширяются (добавляются в ).
USN_REASON_NAMED_DATA_OVERWRITE 0x00000010	Данные в одном или нескольких именованных потоках данных для файла перезаписываются.
USN_REASON_NAMED_DATA_TRUNCATION 0x00000040	Один или несколько именованных потоков данных для файла усекаются.
USN_REASON_OBJECT_ID_CHANGE 0x00080000	Изменяется идентификатор объекта файла или каталога.
USN_REASON_RENAME_NEW_NAME 0x00002000	Файл или каталог будет переименован, а имя файла в структуре USN_RECORD_V4 — это новое имя.
USN_REASON_RENAME_OLD_NAME 0x00001000	Файл или каталог будет переименован, а имя файла в структуре USN_RECORD_V4 — это предыдущее имя.
USN_REASON_REPARSE_POINT_CHANGE 0x00100000	Точка повторной аналитики, содержащаяся в файле или каталоге, изменяется либо точка повторного изменения добавляется в файл или каталог или удаляется из нее.
USN_REASON_SECURITY_CHANGE 0x00000800	В права доступа к файлу или каталогу вносятся изменения.
USN_REASON_STREAM_CHANGE 0x00200000	Именованный поток добавляется в файл или удаляется из него либо именованный поток переименовывается.
USN_REASON_TRANSACTED_CHANGE 0x00400000	Данный поток изменяется с помощью зафиксированной транзакции TxF.

SourceInfo

Дополнительные сведения об источнике изменения, заданные FSCTL_MARK_HANDLE операции DeviceIoControl .

Когда поток записывает новую запись USN, флаги сведений об источнике в предыдущей записи продолжают присутствовать только в том случае, если поток также устанавливает эти флаги. Таким образом, структура исходной информации позволяет приложениям отфильтровать записи USN, которые задаются только известным источником, например фильтром антивирусной программы.

Можно задать одно из следующих значений.

Значение	Значение
USN_SOURCE_AUXILIARY_DATA 0x00000002	Операция добавляет поток частных данных в файл или каталог. Одним из примеров является детектор вирусов, добавляющий сведения о контрольной сумме. По мере того как детектор вирусов изменяет элемент, система создает записи USN. USN_SOURCE_AUXILIARY_DATA указывает, что изменения не изменили данные приложения.
USN_SOURCE_DATA_MANAGEMENT 0x00000001	Операция предоставляет сведения об изменении файла или каталога, внесенного операционной системой. Обычно система удаленного хранилища перемещает данные из внешнего хранилища в локальное. Удаленное хранилище — это программное обеспечение для управления иерархическим хранилищем. Такой шаг обычно как минимум добавляет флаг USN_REASON_DATA_OVERWRITE в запись USN. Однако данные не изменились с точки зрения пользователя. Заметив USN_SOURCE_DATA_MANAGEMENT в элементе SourceInfo , можно определить, что, хотя для элемента выполняется операция записи, данные не изменились.
USN_SOURCE_REPLICATION_MANAGEMENT 0x00000004	Операция изменяет файл в соответствии с содержимым того же файла, который существует в другом элементе набора реплика.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT 0x00000008	Операция заключается в изменении файла в клиентских системах в соответствии с содержимым того же файла, который существует в облаке.

RemainingExtents

Количество экстентов, оставшихся после текущей записи USN_RECORD_V4 . Для описания всех измененных экстентов для данного файла может потребоваться несколько записей версии 4.0. Если элемент RemainingExtents равен 0, текущая запись USN_RECORD_V4 является последней записью USN_RECORD_V4 для файла. За последней записью USN_RECORD_V4 для заданного файла всегда следует запись USN_RECORD_V3 с по крайней мере флагом USN_REASON_CLOSE .

NumberOfExtents

Количество экстентов в текущей записи USN_RECORD_V4 .

ExtentSize

Размер каждой USN_RECORD_EXTENT структуры в элементе Extents в байтах .

Extents[1]

Массив USN_RECORD_EXTENT структур, представляющих экстенты в записи USN_RECORD_V4 .

Запись USN_RECORD_V4 выводится только в том случае, если отслеживание диапазона включено, а размер файла равен или больше значения элемента RangeTrackFileSizeThreshold. Пользователь всегда получает одну или несколько USN_RECORD_V4 записей, за которыми следует одна USN_RECORD_V3 запись.

Чтобы обеспечить прямую совместимость в клиентах журнала изменений, корпорация Майкрософт предоставляет основной и дополнительный номер версии программного обеспечения журнала изменений в структуре USN_RECORD_V4 . Код должен изучить эти значения, проверить собственную совместимость с программным обеспечением журнала изменений и корректно обрабатывать любые несовместимости при необходимости.

Изменение номера дополнительной версии указывает на то, что существующие элементы структуры USN_RECORD_V4 по-прежнему действительны, но новые элементы могут быть добавлены между предпоследним и последним элементом, который является строкой переменной длины.

Для корректной обработки такого изменения код не должен выполнять арифметическую арифметику указателя времени компиляции, которая зависит от расположения последнего элемента. Например, изменение номера дополнительной версии делает sizeof(USN_RECORD) вызов ненадежным. Вместо этого следует использовать вычисления во время выполнения, использующие элемент RecordLength .

Увеличение номера основной версии программного обеспечения журнала изменений указывает на то, что структура USN_RECORD_V4 , возможно, подверглась серьезным изменениям и что текущее определение может быть ненадежным. Если код обнаруживает изменение основного номера версии программного обеспечения журнала изменений, код не должен работать с журналом изменений.

Дополнительные сведения см. в статье Создание, изменение и удаление Журнал изменений.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 R2 [только классические приложения]
Верхняя часть	winioctl.h (включая Windows.h)