SHChangeNotifyRegister 函式 (shlobj_core.h)

發行項
03/15/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 旗標結合。使用此旗標時，也必須將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 時，應該一律將此陣列設定為一個陣列，將無法正常運作。

傳回值

類型： ULONG

傳回正整數註冊識別碼。如果記憶體不足或回應不正確參數，則傳回 0。

備註

如需示範如何使用此函式的完整範例，請參閱 Windows 軟體發展工具組中的變更通知監看員範例 (SDK) 。

引發變更通知事件時， 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 起不再提供，相當於具有 SHCNRF_NewDelivery 旗標的SHChangeNotifyRegister。

規格需求


最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	shlobj_core.h (包含 Shlobj.h)
程式庫	Shell32.lib
Dll	Shell32.dll (5.0 版或更新版本)
API 集合	ext-ms-win-shell32-l1-2-1 (于 Windows 10 10.0.10240 版)