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

  • Статья

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

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

Синтаксис

HANDLE FindFirstChangeNotificationA(
  [in] LPCSTR 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 Да
SMB 3.0 Transparent Failover (TFO) Да
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