Функция FindFirstChangeNotificationW (fileapi.h)

  • Статья

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

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

Синтаксис

HANDLE FindFirstChangeNotificationW(
  [in] LPCWSTR lpPathName,
  [in] BOOL    bWatchSubtree,
  [in] DWORD   dwNotifyFilter
);

Параметры

[in] lpPathName

Полный путь к каталогу для отслеживания.

Это не может быть относительный путь или пустая строка.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

[in] bWatchSubtree

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

[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_SECURITY
0x00000100
 Любое изменение дескриптора безопасности в отслеживаемом каталоге или поддереве приводит к возврату операции ожидания уведомления об изменениях.

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

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

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

Комментарии

Функции ожидания могут отслеживать указанный каталог или поддерево с помощью дескриптора, возвращаемого функцией FindFirstChangeNotification. Ожидание выполняется при возникновении одного из условий фильтра в отслеживаемом каталоге или поддереве.

После выполнения ожидания приложение может отреагировать на это условие и продолжить мониторинг каталога, вызвав функцию FindNextChangeNotification и соответствующую функцию ожидания. Если дескриптор больше не нужен, его можно закрыть с помощью функции FindCloseChangeNotification .

Уведомления могут не возвращаться при вызове Метода FindFirstChangeNotification для удаленной файловой системы.

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

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

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

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

Приложение может столкнуться с ложными срабатываниями при приостановке или возобновлении работы CSVF.

Примеры

Пример см. в разделе Получение Change_Notifications каталога.

Примечание

Заголовок fileapi.h определяет FindFirstChangeNotification как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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

См. также

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

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW