Поделиться через


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

Содержит сведения для записи журнала изменений версии 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.

Комментарии

В выходных буферах, возвращаемых операциями DeviceIoControl , которые работают с USN_RECORD_V3, все записи выравниваются по 64-разрядным границам с начала буфера.

Если отслеживание диапазона включено, NTFS переключается на создание только 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)

См. также раздел

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V2

структура USN_RECORD_V4

Структуры управления томами