Функция SHChangeNotifyRegister (shlobj_core.h)

Статья
08/26/2023

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

Синтаксис

ULONG SHChangeNotifyRegister(
  [in] HWND                      hwnd,
       int                       fSources,
       LONG                      fEvents,
       UINT                      wMsg,
       int                       cEntries,
  [in] const SHChangeNotifyEntry *pshcne
);

Параметры

[in] hwnd

Тип: HWND

Дескриптор окна, получающего сообщения об изменениях или уведомлениях.

fSources

Тип: int

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

Примечание В более ранних версиях пакета SDK эти флаги не определены в файле заголовка, и разработчики должны сами определять эти значения или использовать их числовые значения напрямую. В Windows Vista эти флаги определены в файле Shlobj.h.

SHCNRF_InterruptLevel (0x0001)

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

SHCNRF_ShellLevel (0x0002)

Уведомления на уровне оболочки из оболочки.

SHCNRF_RecursiveInterrupt (0x1000)

События прерывания для всего поддеревья. Этот флаг должен быть объединён с флагом SHCNRF_InterruptLevel . При использовании этого флага уведомления также должны быть рекурсивными, задав для элемента fRecursive соответствующей структуры SHChangeNotifyEntry , на которую ссылается pshcne , значение TRUE. Использование SHCNRF_RecursiveInterrupt в одноуровневом представлении, например относительное значение PIDL и содержащее только один ИДЕНТИФИКАТОР SHITEMID, заблокирует уведомление о событиях на самом высоком уровне и тем самым предотвратит рекурсивное дочернее обновление. Таким образом, значок, перетаскиваемый на самый низкий уровень иерархии папок, может не отображаться в представлении должным образом.

SHCNRF_NewDelivery (0x8000)

Полученные сообщения используют общую память. Вызовите SHChangeNotification_Lock для доступа к фактическим данным. Вызовите SHChangeNotification_Unlock , чтобы освободить память по завершении.

Примечание Мы рекомендуем использовать этот флаг, так как он обеспечивает более надежный метод доставки. Все клиенты должны указывать этот флаг.

fEvents

Тип: LONG

События уведомления об изменениях, для которых требуется получать уведомление. Возможные значения см. в разделе Флаги SHCNE, перечисленные в SHChangeNotify .

wMsg

Тип: UINT

Сообщение, которое будет отправлено в процедуру окна.

cEntries

Тип: int

Количество записей в массиве pshcne .

[in] pshcne

Тип: const SHChangeNotifyEntry*

Массив структур SHChangeNotifyEntry , содержащих уведомления. Этот массив всегда должен иметь значение , если вызов SHChangeNotifyRegister или SHChangeNotifyDeregister не будет работать должным образом.

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

Тип: ULONG

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

Полный пример, демонстрирующий использование этой функции, см. в разделе Пример уведомления об изменениях в пакете средств разработки программного обеспечения (SDK) для Windows.

При возникновении события уведомления об изменении сообщение, указанное wMsg , доставляется в окно, указанное параметром hwnd .

Если указано SHCNRF_NewDelivery, значения wParam и lParam в сообщении должны передаваться в SHChangeNotification_Lock в качестве параметров hChange и dwProcID соответственно.
Если SHCNRF_NewDelivery не указан, wParam является указателем на два PIDLIST_ABSOLUTE указателя, а lParam указывает событие. В зависимости от отправляемого события два указателя PIDLIST_ABSOLUTE могут иметь значение NULL.

Если происходит соответствующее событие файловой системы и параметр hwnd не равен NULL, сообщение, указанное wMsg , публикуется в указанном окне. В противном случае, если параметр pshcne не равен NULL, используется эта запись уведомления.

По соображениям производительности несколько уведомлений можно объединить в одно уведомление. Например, если для файлов в одной папке создается большое количество уведомлений SHCNE_UPDATEITEM , их можно объединить в одно уведомление SHCNE_UPDATEDIR .

Функция NTSHChangeNotifyRegister , которая больше не доступна в Windows Vista, была эквивалентна SHChangeNotifyRegister с флагом SHCNRF_NewDelivery.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	shlobj_core.h (включая Shlobj.h)
Библиотека	Shell32.lib
DLL	Shell32.dll (версия 5.0 или более поздняя)
Набор API	ext-ms-win-shell-shell32-l1-2-1 (представлено в Windows 10 версии 10.0.10240)