SHChangeNotifyRegister function (shlobj_core.h)
Registers a window to receive notifications from the file system or Shell, if the file system supports notifications.
Syntax
ULONG SHChangeNotifyRegister(
[in] HWND hwnd,
int fSources,
LONG fEvents,
UINT wMsg,
int cEntries,
[in] const SHChangeNotifyEntry *pshcne
);
Parameters
[in] hwnd
Type: HWND
A handle to the window that receives the change or notification messages.
fSources
Type: int
One or more of the following values that indicate the type of events for which to receive notifications.
SHCNRF_InterruptLevel (0x0001)
Interrupt level notifications from the file system.
SHCNRF_ShellLevel (0x0002)
Shell-level notifications from the shell.
SHCNRF_RecursiveInterrupt (0x1000)
Interrupt events on the whole subtree. This flag must be combined with the SHCNRF_InterruptLevel flag. When using this flag, notifications must also be made recursive by setting the fRecursive member of the corresponding SHChangeNotifyEntry structure referenced by pshcne to TRUE. Use of SHCNRF_RecursiveInterrupt on a single level view—for example, a PIDL that is relative and contains only one SHITEMID—will block event notification at the highest level and thereby prevent a recursive, child update. Thus, an icon dragged into the lowest level of a folder hierarchy may fail to appear in the view as expected.
SHCNRF_NewDelivery (0x8000)
Messages received use shared memory. Call SHChangeNotification_Lock to access the actual data. Call SHChangeNotification_Unlock to release the memory when done.
fEvents
Type: LONG
Change notification events for which to receive notification. See the SHCNE flags listed in SHChangeNotify for possible values.
wMsg
Type: UINT
Message to be posted to the window procedure.
cEntries
Type: int
Number of entries in the pshcne array.
[in] pshcne
Type: const SHChangeNotifyEntry*
Array of SHChangeNotifyEntry structures that contain the notifications. This array should always be set to one when calling SHChangeNotifyRegister or SHChangeNotifyDeregister will not work properly.
Return value
Type: ULONG
Returns a positive integer registration ID. Returns 0 if out of memory or in response to invalid parameters.
Remarks
See the Change Notify Watcher Sample in the Windows Software Development Kit (SDK) for a full example that demonstrates the use of this function.
When a change notification event is raised, the message indicated by wMsg is delivered to the window specified by the hwnd parameter.
- If SHCNRF_NewDelivery is specified, the wParam and lParam values in the message should be passed to SHChangeNotification_Lock as the hChange and dwProcID parameters respectively.
- If SHCNRF_NewDelivery is not specified, wParam is a pointer to two PIDLIST_ABSOLUTE pointers, and lParam specifies the event. The two PIDLIST_ABSOLUTE pointers can be NULL, depending on the event being sent.
For performance reasons, multiple notifications can be combined into a single notification. For example, if a large number of SHCNE_UPDATEITEM notifications are generated for files in the same folder, they can be joined into a single SHCNE_UPDATEDIR notification.
The NTSHChangeNotifyRegister function, which is no longer available as of Windows Vista, was equivalent to SHChangeNotifyRegister with the SHCNRF_NewDelivery flag.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 2000 Professional [desktop apps only] |
Minimum supported server | Windows 2000 Server [desktop apps only] |
Target Platform | Windows |
Header | shlobj_core.h (include Shlobj.h) |
Library | Shell32.lib |
DLL | Shell32.dll (version 5.0 or later) |
API set | ext-ms-win-shell-shell32-l1-2-1 (introduced in Windows 10, version 10.0.10240) |