структура 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 запись журнала изменений должна иметь по крайней мере один из этих флагов.
Список допустимых флагов выглядит следующим образом. Неиспользуемые биты зарезервированы.
| Значение | Значение |
|---|---|
|
Пользователь изменил один или несколько атрибутов файла или каталога (например, атрибут только для чтения, скрытый, системный, архивный или разреженный атрибут) или одну или несколько меток времени. |
|
Файл или каталог закрыт. |
|
Состояние сжатия файла или каталога изменяется с или на сжатое. |
|
Файл или каталог добавляется в . |
|
Данные в файле или каталоге перезаписываются. |
|
Файл или каталог усечен. |
|
Пользователь вносит изменения в расширенные атрибуты файла или каталога. Эти атрибуты файловой системы NTFS недоступны для приложений windows. |
|
Файл или каталог шифруются или расшифровываются. |
|
Файл или каталог создается в первый раз. |
|
Файл или каталог будут удалены. |
|
Жесткая ссылка файловой системы NTFS добавляется в файл или каталог или удаляется из него. Жесткая ссылка файловой системы NTFS, аналогичная жесткой ссылке POSIX, является одной из нескольких записей каталога, которые видят один и тот же файл или каталог. |
|
Пользователь изменил атрибут FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . То есть пользователь изменил файл или каталог с файла, который можно индексировать, на файл, который не может быть индексирован, или наоборот. (Индексирование контента позволяет быстро искать данные, создавая базу данных выбранного содержимого.) |
|
В был добавлен один или несколько именованных потоков данных для файла. |
|
Данные в одном или нескольких именованных потоках данных для файла перезаписываются. |
|
Один или несколько именованных потоков данных для файла усекаются. |
|
Изменяется идентификатор объекта файла или каталога. |
|
Файл или каталог переименовываются, а имя файла в USN_RECORD_V2 или USN_RECORD_V3 структуре, в которой содержится эта запись журнала, является новым именем. |
|
Файл или каталог переименовываются, а имя файла в USN_RECORD_V2 или USN_RECORD_V3 структуре, в которой содержится эта запись журнала, является предыдущим именем. |
|
Точка повторного выполнения, содержащаяся в файле или каталоге, изменяется либо точка повторного изменения добавляется в файл или каталог или удаляется из нее. |
|
В разрешениях на доступ к файлу или каталогу вносятся изменения. |
|
Именованный поток добавляется в файл или каталог или удаляется из него, либо именованный поток переименовывается. |
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) |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по