структура 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 запись журнала изменений должна иметь по крайней мере один из этих флагов.

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

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 .

Требования

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

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD