SHChangeNotifyRegister 函数 (shlobj_core.h)

  • 项目

注册一个窗口以接收来自文件系统或 Shell 的通知（如果文件系统支持通知）。

语法

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)

来自 shell 的 Shell 级通知。

SHCNRF_RecursiveInterrupt (0x1000)

中断整个子树上的事件。 此标志必须与 SHCNRF_InterruptLevel 标志组合使用。 使用此标志时，还必须通过将 pshcne 引用的相应 SHChangeNotifyEntry 结构的 fRecursive 成员设置为 TRUE，使通知成为递归通知。 在单个级别视图中使用 SHCNRF_RecursiveInterrupt （例如，相对的且仅包含一个 SHITEMID 的 PIDL）将阻止最高级别的事件通知，从而阻止递归子更新。 因此，拖到文件夹层次结构最低级别的图标可能无法按预期显示在视图中。

SHCNRF_NewDelivery (0x8000)

收到的消息使用共享内存。 调用 SHChangeNotification_Lock 以访问实际数据。 调用 SHChangeNotification_Unlock 以在完成后释放内存。

注意 建议使用此标志，因为它提供更可靠的传递方法。 所有客户端都应指定此标志。
 

fEvents

类型： LONG

更改要接收通知的通知事件。 有关可能的值，请参阅 SHChangeNotify 中列出的 SHCNE 标志。

wMsg

类型： UINT

要发布到窗口过程的消息。

cEntries

类型： int

pshcne 数组中的条目数。

[in] pshcne

类型： const SHChangeNotifyEntry*

包含通知的 SHChangeNotifyEntry 结构的数组。 当调用 SHChangeNotifyRegister 或 SHChangeNotifyDeregister 无法正常工作时，应始终将此数组设置为 1。

返回值

类型： ULONG

返回正整数注册 ID。 如果内存不足或响应无效参数，则返回 0。

注解

有关演示如何使用此函数的完整示例，请参阅 Windows 软件开发工具包 (SDK) 中的 更改通知观察程序示例 。

当引发更改通知事件时， wMsg 指示的消息将传递到 hwnd 参数指定的窗口。

  • 如果指定了SHCNRF_NewDelivery，则应将消息中的 wParam 和 lParam 值分别作为 hChange 和 dwProcID 参数传递给 SHChangeNotification_Lock。
  • 如果未指定SHCNRF_NewDelivery， 则 wParam 是指向两个PIDLIST_ABSOLUTE指针的指针， lParam 指定事件。 两个PIDLIST_ABSOLUTE指针可以为 NULL，具体取决于要发送的事件。
当发生相关文件系统事件并且 hwnd 参数不为 NULL 时， wMsg 指示的消息将发布到指定的窗口。 否则，如果 pshcne 参数不为 NULL，则使用该通知条目。

出于性能原因，可以将多个通知组合成一个通知。 例如，如果为同一文件夹中的文件生成了大量 SHCNE_UPDATEITEM 通知，则可以将其联接到单个 SHCNE_UPDATEDIR 通知中。

NTSHChangeNotifyRegister 函数在 Windows Vista 中不再可用，它等效于具有 SHCNRF_NewDelivery 标志的 SHChangeNotifyRegister。

要求

   
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 shlobj_core.h (包括 Shlobj.h)
Library Shell32.lib
DLL Shell32.dll (5.0 或更高版本)
API 集 ext-ms-win-shell-shell32-l1-2-1 (在 Windows 10 版本 10.0.10240 中引入)