FindNextChangeNotification Function (Windows)

FindNextChangeNotification Function

Requests that the operating system signal a change notification handle the next time it detects an appropriate change.

Syntax

C++

BOOL WINAPI FindNextChangeNotification(
  __in  HANDLE hChangeHandle
);

Parameters

hChangeHandle [in]: A handle to a change notification handle created by the FindFirstChangeNotification function.

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

After the FindNextChangeNotification function returns successfully, the application can wait for notification that a change has occurred by using the wait functions.

If a change occurs after a call to FindFirstChangeNotification but before a call to FindNextChangeNotification, the operating system records the change. When FindNextChangeNotification is executed, the recorded change immediately satisfies a wait for the change notification.

FindNextChangeNotification should not be used more than once on the same handle without using one of the wait functions. An application may miss a change notification if it uses FindNextChangeNotification when there is a change request outstanding.

When hChangeHandle is no longer needed, close it by using the FindCloseChangeNotification function.

Examples

For an example, see Obtaining Directory Change Notifications.

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	WinBase.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

You must only re-create your next find-handle using FindNextChangeNotification() if that find-hand has signalled that "a change happened". In other words, only call FindNextChangeNotification() when the wait function returns something like WAIT_OBJECT_0. Otherwise your process will (in all cases I've seen) leak Non-Paged pool memory.

Unconditionally calling FindNextChangeNotification() in your file/directory monitoring loop will leak Non-Paged pool memory.

Non-Paged pool memory is a limited resource. You can bring down (or stall) the OS if you use too much of it.

Obviously I've just found some code written by a very sensible/knowledgeable fellow who happened to fall fowl of this problem. So it can happen.

Reproducing the problem

Start with the example above: Obtaining Directory Change Notifications.

Modify the while loop in the WatchDirectory() function such that:

1. we have finite time-out:

dwWaitStatus = WaitForMultipleObjects(2, dwChangeHandles, FALSE, 500);

2. Replace the the WAIT_TIMEOUT branch, doing a silly call to FindNextChangeNotification()

case WAIT_TIMEOUT:
// A timeout occurred
printf("\nNo changes in the timeout period.\n");

if (FindNextChangeNotification(dwChangeHandles[1]) )
{
printf("\n done waste full FindNextChangeNotification() call!\n");
}else{
printf("\n ERROR: FindNextChangeNotification function failed.\n");
ExitProcess(GetLastError()); 
}

break;

Run this app. Note in task manager that app's non-paged pool memory allocation will climb without limit.

Caveat

I hope all the above is generally true/correct.