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

Статья
03/08/2023

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

Синтаксис

typedef struct {
  DWORD         RecordLength;
  WORD          MajorVersion;
  WORD          MinorVersion;
  FILE_ID_128   FileReferenceNumber;
  FILE_ID_128   ParentFileReferenceNumber;
  USN           Usn;
  LARGE_INTEGER TimeStamp;
  DWORD         Reason;
  DWORD         SourceInfo;
  DWORD         SecurityId;
  DWORD         FileAttributes;
  WORD          FileNameLength;
  WORD          FileNameOffset;
  WCHAR         FileName[1];
} USN_RECORD_V3, *PUSN_RECORD_V3;

Члены

RecordLength

Общая длина записи в байтах.

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

Размер любой записи журнала изменений в байтах не может превышать размер структуры USN_RECORD_V3 , а символы MaximumComponentLength минус 1 (для символа, объявленного в структуре) раз больше размера широкого символа. Значение Параметра MaximumComponentLength можно определить путем вызова
Функция GetVolumeInformation. В C размер записи можно определить с помощью следующего примера кода.

C++
MaximumChangeJournalRecordSize = QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR) + sizeof(USN_RECORD_V3) );

Чтобы обеспечить совместимость между изменениями версий программного обеспечения журнала изменений, используйте вычисление во время выполнения, чтобы определить размер структуры USN_RECORD_V3 . Дополнительные сведения о совместимости между изменениями версий см. в разделе Примечания этой статьи.

MajorVersion

Основной номер версии программного обеспечения журнала изменений для этой записи.

Например, если программное обеспечение журнала изменений имеет версию 3.0, основной номер версии — 3.

Значение	Значение
2	Структура является USN_RECORD_V2 структурой, и остальная часть структуры должна быть проанализирована с помощью этого макета.
3	Структура является USN_RECORD_V3 структурой, и остальная часть структуры должна быть проанализирована с помощью этого макета.
4	Структура является [USN_RECORD_V4 структура](ns-winioctl-usn_record_v4.md), а остальная часть структуры должна быть проанализирована с помощью этого макета.

MinorVersion

Дополнительный номер версии программного обеспечения журнала изменений для этой записи. Например, если программное обеспечение журнала изменений — версия 3.0, дополнительный номер версии равен нулю.

FileReferenceNumber

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

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

ParentFileReferenceNumber

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

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

Usn

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

TimeStamp

Стандартная метка времени в формате UTC (FILETIME) этой записи в 64-разрядном формате.

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	Пользователь внес изменения в расширенные атрибуты файла или каталога.
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_V3 — это новое имя.
USN_REASON_RENAME_OLD_NAME 0x00001000	Файл или каталог переименован, а имя файла в структуре USN_RECORD_V3 — это предыдущее имя.
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	Операция изменяет файл в клиентских системах в соответствии с содержимым того же файла, который существует в облаке.

SecurityId

Уникальный идентификатор безопасности, назначенный файлу или каталогу, связанному с этой записью.

FileAttributes

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

FileNameLength

Длина имени файла или каталога, связанного с этой записью, в байтах. Элемент FileName содержит это имя. Используйте этот элемент для определения длины имени файла, а не в зависимости от конечного значения "\0", чтобы разделять имя файла в FileName.

FileNameOffset

Смещение элемента FileName от начала структуры.

FileName[1]

Имя файла или каталога, связанного с этой записью, в формате Юникода. Это имя файла или каталога имеет переменную длину.

При работе с FileName не следует рассчитывать на имя файла, содержащее конечный разделитель "\0", а вместо этого определите длину имени файла с помощью FileNameLength.

Не выполняйте арифметические указатели времени компиляции с помощью FileName. Вместо этого выполните необходимые вычисления во время выполнения, используя значение члена FileNameOffset . Это поможет сделать код совместимым с любыми будущими версиями USN_RECORD_V3.

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

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

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

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

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

Требования

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