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

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

  • Статья

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

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

Синтаксис

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.

Комментарии

Чтобы получить дескриптор для каталога, используйте функцию CreateFile с флагом FILE_FLAG_BACKUP_SEMANTICS .

Вызов 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

См. также

CreateFile

CreateIoCompletionPort

Функции управления каталогами

FILE_NOTIFY_INFORMATION

FileIOCompletionRoutine

GetOverlappedResult

GetQueuedCompletionStatus

ПЕРЕКРЫВАЮЩИХСЯ