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

Статья
08/27/2023

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

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

Синтаксис

BOOL ReadDirectoryChangesW(
  [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] hDirectory

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

[out] lpBuffer

Указатель на буфер формата, выровненный по DWORD, в который должны возвращаться результаты чтения. Структура этого буфера определяется структурой FILE_NOTIFY_INFORMATION . Этот буфер заполняется синхронно или асинхронно в зависимости от того, как открывается каталог и какое значение присваивается параметру 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
Прозрачная отработка отказа (TFO) SMB 3.0	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

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

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

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll