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

Статья
11/20/2024

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

Эта функция не указывает на изменение, удовлетворяющее условию ожидания. Чтобы получить сведения об определенном изменении в рамках уведомления, используйте
функция 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 (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	См. примечание
Отказоустойчивая файловая система (ReFS)	Да

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

Примеры

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	fileapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

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

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW

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