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


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

Содержит сведения, определяющие набор записей журнала изменений последовательного номера обновления (USN) для возврата в вызывающий процесс. Используется кодами элементов управления FSCTL_QUERY_USN_JOURNAL и FSCTL_READ_USN_JOURNAL . До Windows 8 и Windows Server 2012 эта структура называлась READ_USN_JOURNAL_DATA. Используйте это имя для компиляции с помощью старых пакетов SDK и компиляторов. Windows Server 2012 появились READ_USN_JOURNAL_DATA_V1 для поддержки 128-разрядных идентификаторов файлов, используемых ReFS.

Синтаксис

typedef struct {
  USN       StartUsn;
  DWORD     ReasonMask;
  DWORD     ReturnOnlyOnClose;
  DWORDLONG Timeout;
  DWORDLONG BytesToWaitFor;
  DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;

Члены

StartUsn

Номер usn, с которого начинается чтение журнала изменений.

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

Чтобы начать операцию чтения с определенной записи, задайте для параметра StartUsn значение usn этой записи.

Если указан ненулевой номер USN, который меньше первого usn в журнале изменений, возникает ошибка и возвращается код ошибки ERROR_JOURNAL_ENTRY_DELETED . Этот код может указывать на случай, когда указанный USN является допустимым одновременно, но с тех пор был удален.

Дополнительные сведения о навигации по буферу журнала изменений, возвращаемого в READ_USN_JOURNAL_DATA_V0, см. в разделе Обход буфера записей журнала изменений.

ReasonMask

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

Список допустимых флагов выглядит следующим образом. Неиспользуемые биты зарезервированы.

Значение Значение
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_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_V2 или USN_RECORD_V3 структуре, в которой содержится эта запись журнала, является новым именем.
USN_REASON_RENAME_OLD_NAME
0x00001000
Файл или каталог переименовываются, а имя файла в USN_RECORD_V2 или USN_RECORD_V3 структуре, в которой содержится эта запись журнала, является предыдущим именем.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
Точка повторного выполнения, содержащаяся в файле или каталоге, изменяется либо точка повторного изменения добавляется в файл или каталог или удаляется из нее.
USN_REASON_SECURITY_CHANGE
0x00000800
В разрешениях на доступ к файлу или каталогу вносятся изменения.
USN_REASON_STREAM_CHANGE
0x00200000
Именованный поток добавляется в файл или каталог или удаляется из него, либо именованный поток переименовывается.

ReturnOnlyOnClose

Значение типа , указывающее, когда следует возвращать записи журнала изменений.

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

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

Чтобы получать уведомление при первом регистрации каждого изменения, а также при очистке задайте для параметра ReturnOnlyOnClose значение 0.

Независимо от того, равен ли ReturnOnlyOnClose нулю или ненулевому значению, записи, созданные при очистке журнала изменений в журнале изменений в usn, которые произошли с файлом или каталогом. Каждый раз, когда выполняется окончательная операция закрытия элемента, запись закрытия usn записывается в журнал изменений, и все флаги ReasonMask для элемента сбрасываются.

Для файла или каталога, для которых нет данных пользователя (например, подключенной папки), последняя операция закрытия происходит при вызове функции CloseHandle для последнего пользовательского дескриптора элемента.

Timeout

Значение времени ожидания в секундах, используемое с элементом BytesToWaitFor , чтобы сообщить операционной системе, что делать, если операция FSCTL_READ_USN_JOURNAL запрашивает больше данных, чем существует в журнале изменений.

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

Если время ожидания не равно нулю, а значение BytesToWaitFor — ненулевое, а вызов операции FSCTL_READ_USN_JOURNAL достигает конца журнала изменений, не находя возвращаемых данных, FSCTL_READ_USN_JOURNAL ожидает время ожидания секунд, а затем пытается вернуть указанные записи. По истечении времени ожиданияFSCTL_READ_USN_JOURNAL извлекает все записи, доступные в указанном диапазоне.

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

Если значение BytesToWaitFor равно нулю, время ожидания игнорируется. Время ожидания также игнорируется для асинхронно открытых дескрипторов.

BytesToWaitFor

Количество байтов неотфильтрованных данных, добавленных в журнал изменений. Используйте это значение со значением Timeout , чтобы сообщить операционной системе, что делать, если операция FSCTL_READ_USN_JOURNAL запрашивает больше данных, чем существует в журнале изменений.

Если значение BytesToWaitFor равно нулю, время ожидания игнорируется. В этом случае операция FSCTL_READ_USN_JOURNAL всегда возвращается успешно при обнаружении конца файла журнала изменений. Он также извлекает usn, который должен использоваться для следующей операции FSCTL_READ_USN_JOURNAL . Если возвращенный следующий номер USN совпадает с предоставленным параметром StartUsn , записи отсутствуют. Вызывающий процесс не должен использовать FSCTL_READ_USN_JOURNAL немедленно.

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

Кроме того, используйте параметр lpBytesReturnedобъекта DeviceIoControl в вызове операции FSCTL_READ_USN_JOURNAL , чтобы определить объем доступных данных, перераспределить выходной буфер (с местом для новых записей) и снова вызвать DeviceIoControl .

UsnJournalID

Идентификатор экземпляра журнала, текущего для тома.

Файловая система NTFS может не помещать события в журнал изменений, если журнал изменений остановлен, перезапущен или удален и создан повторно. При возникновении любого из этих событий файловая система NTFS предоставляет журналу новый идентификатор. Если идентификатор журнала не согласен с текущим идентификатором журнала, вызов DeviceIoControl завершается ошибкой и возвращает соответствующий код ошибки. Чтобы получить новый идентификатор журнала, вызовите DeviceIoControl с операцией FSCTL_QUERY_USN_JOURNAL .

Требования

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

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

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD