Функция 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
Условия фильтра, удовлетворяющие ожиданию уведомления об изменениях. Этот параметр может быть одним или несколькими из следующих значений.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение является дескриптором для объекта уведомления об изменении поиска.
Если функция завершается неудачно, возвращается значение 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 |