Функция ReadDirectoryChangesExW (winbase.h)

Статья
08/27/2023

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

Сведения о отслеживании изменений тома см. в журналах изменений.

Синтаксис

BOOL ReadDirectoryChangesExW(
  [in]                HANDLE                                  hDirectory,
  [out]               LPVOID                                  lpBuffer,
  [in]                DWORD                                   nBufferLength,
  [in]                BOOL                                    bWatchSubtree,
  [in]                DWORD                                   dwNotifyFilter,
  [out, optional]     LPDWORD                                 lpBytesReturned,
  [in, out, optional] LPOVERLAPPED                            lpOverlapped,
  [in, optional]      LPOVERLAPPED_COMPLETION_ROUTINE         lpCompletionRoutine,
  [in]                READ_DIRECTORY_NOTIFY_INFORMATION_CLASS ReadDirectoryNotifyInformationClass
);

Параметры

[in] hDirectory

Дескриптор отслеживаемого каталога. Этот каталог должен быть открыт с FILE_LIST_DIRECTORY правом доступа или с таким правом доступа, как GENERIC_READ , включающее право доступа FILE_LIST_DIRECTORY .

[out] lpBuffer

Указатель на буфер формата, выровненный по DWORD, в котором ReadDirectoryChangesExW должен возвращать результаты чтения. Структура этого буфера определяется структурой FILE_NOTIFY_EXTENDED_INFORMATION , если параметр ReadDirectoryNotifyInformationClass имеет значение ReadDirectoryNotifyExtendedInformation, или структурой FILE_NOTIFY_INFORMATION , если ReadDirectoryNotifyInformationClass имеет значение ReadDirectoryNotifyInformationInformation.

Этот буфер заполняется синхронно или асинхронно в зависимости от того, как открывается каталог и какое значение присваивается параметру lpOverlapped . Дополнительные сведения см. в разделе «Примечания».

[in] nBufferLength

Размер буфера, на который указывает параметр lpBuffer , в байтах.

[in] bWatchSubtree

Если этот параметр имеет значение TRUE, функция отслеживает дерево каталогов, корнями в указанном каталоге. Если этот параметр имеет значение FALSE, функция отслеживает только каталог, указанный параметром hDirectory .

[in] dwNotifyFilter

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

Значение	Значение
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Любое изменение имени файла в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменении. Изменения включают переименование, создание или удаление файла.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Любое изменение имени каталога в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменении. Изменения включают создание или удаление каталога.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Любое изменение атрибута в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменении.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Любое изменение размера файла в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменении. Операционная система обнаруживает изменение размера файла только в том случае, если файл записывается на диск. В операционных системах с интенсивным использованием кэширования обнаружение происходит только при достаточной очистке кэша.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Любое изменение времени последней записи файлов в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменении. Операционная система обнаруживает изменение последнего времени записи файла только в том случае, если файл записывается на диск. В операционных системах с интенсивным использованием кэширования обнаружение происходит только при достаточной очистке кэша.
FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020	Любое изменение времени последнего доступа к файлам в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменениях.
FILE_NOTIFY_CHANGE_CREATION 0x00000040	Любое изменение времени создания файлов в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменениях.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Любое изменение дескриптора безопасности в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменениях.

[out, optional] lpBytesReturned

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

[in, out, optional] lpOverlapped

Указатель на структуру OVERLAPPED , которая предоставляет данные для использования во время асинхронной операции. В противном случае это значение равно NULL. Элементы Offset и OffsetHigh этой структуры не используются.

[in, optional] lpCompletionRoutine

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

[in] ReadDirectoryNotifyInformationClass

Тип сведений, которые ReadDirectoryChangesExW должен записывать в буфер, на который указывает параметр lpBuffer . Укажите ReadDirectoryNotifyInformation , чтобы указать, что информация должна состоять из FILE_NOTIFY_INFORMATION структур, или ReadDirectoryNotifyExtendedInformation , чтобы указать, что информация должна состоять из FILE_NOTIFY_EXTENDED_INFORMATION структур.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение. Для синхронных вызовов это означает, что операция выполнена успешно. Для асинхронных вызовов это означает, что операция успешно поставлена в очередь.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Если перенаправитель сети или целевая файловая система не поддерживают эту операцию, функция завершается сбоем с ERROR_INVALID_FUNCTION.

Вызов ReadDirectoryChangesExW можно выполнить синхронно или асинхронно. Чтобы указать асинхронное завершение, откройте каталог createFile , как показано выше, но дополнительно укажите атрибут FILE_FLAG_OVERLAPPED в параметре dwFlagsAndAttributes . Затем укажите структуру OVERLAPPED при вызове ReadDirectoryChangesExW.

При первом вызове ReadDirectoryChangesExW система выделяет буфер для хранения сведений об изменениях. Этот буфер связывается с дескриптором каталога до тех пор, пока он не будет закрыт, а его размер не изменится в течение всего времени существования. Изменения каталога, происходящие между вызовами этой функции, добавляются в буфер, а затем возвращаются при следующем вызове. Если буфер переполнен, ReadDirectoryChangesExW по-прежнему возвращает значение true, но все содержимое буфера удаляется, а параметр lpBytesReturned будет равен нулю, что означает, что буфер был слишком мал для хранения всех внесенных изменений.

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

Для асинхронного завершения можно получать уведомления одним из трех способов:

Использование функции GetOverlappedResult . Чтобы получать уведомления через GetOverlappedResult, не указывайте подпрограмму завершения в параметре lpCompletionRoutine . Обязательно задайте для элемента hEvent структуры OVERLAPPED уникальное событие.
Использование функции GetQueuedCompletionStatus . Чтобы получать уведомления через GetQueuedCompletionStatus, не указывайте подпрограмму завершения в lpCompletionRoutine. Свяжите дескриптор каталога hDirectory с портом завершения, вызвав функцию CreateIoCompletionPort .
Использование процедуры завершения. Чтобы получать уведомления через подпрограмму завершения, не свяжите каталог с портом завершения. Укажите подпрограмму завершения в lpCompletionRoutine. Эта подпрограмма вызывается всякий раз, когда операция была завершена или отменена, пока поток находится в состоянии ожидания с возможностью предупреждения. Элемент hEvent структуры OVERLAPPED не используется системой, поэтому его можно использовать самостоятельно.

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

ReadDirectoryChangesExW завершается сбоем с ERROR_INVALID_PARAMETER , если длина буфера превышает 64 КБ и приложение отслеживает каталог по сети. Это связано с ограничением размера пакета с базовыми протоколами общего доступа к файлам.

ReadDirectoryChangesExW завершается сбоем с ERROR_NOACCESS , если буфер не выровнен по границе DWORD .

ReadDirectoryChangesExW завершается сбоем с ERROR_NOTIFY_ENUM_DIR , когда системе не удалось записать все изменения в каталог. В этом случае необходимо вычислить изменения путем перечисления каталога или поддеревья.

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

ReadDirectoryChangesExW в настоящее время поддерживается только для файловой системы NTFS.

Транзакция операций

Если транзакция привязана к дескриптору каталога, уведомления следуют соответствующим правилам изоляции транзакций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 10, версия 1709 [только классические приложения]
Минимальная версия сервера	Windows Server 2019 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll