GetQueuedCompletionStatusEx(), ReadDirectoryChangesW()

Question

I am using GetQueuedCompletionStatusEx() and ReadDirectoryChangesW() to try to receive notifications of changes to multiple filesystem hierarchies.

I noticed that I would receive completion packets with error 0x10C when there would be a lot of changes at once. This error code wasn't anywhere in the header files I'd included and wasn't in the documentation ( http://msdn.microsoft.com/en-us/library/windows/desktop/aa365465(v=vs.85).aspx ). A little digging later, I find out that it's STATUS_NOTIFY_ENUM_DIR defined in ntstatus.h. Neither STATUS_NOTIFY_ENUM_DIR is mentioned in the documentation nor is the necessity of including ntstatus.h. MSDN indicates that it should have been ERROR_NOTIFY_ENUM_DIR. So I am wondering, is this a bug in the documentation or perhaps I am doing something wrong?

Answer 1

ERROR_NOTIFY_ENUM_DIR is defined in winerror.h:

//
// MessageId: ERROR_NOTIFY_ENUM_DIR
//
// MessageText:
//
// A notify change request is being completed and the information is not being returned in the caller's buffer. The caller now needs to enumerate the files to find the changes.
//
#define ERROR_NOTIFY_ENUM_DIR            1022L

However, 1022 is 0x3FE. 0x10C is 268 instead, which is not an error code that ReadDirectoryChangesW() is supposed to return. So if ReadDirectoryChangesW() is directly returning STATUS_NOTIFY_ENUM_DIR instead of translating it into ERROR_NOTIFY_ENUM_DIR, then that very well could be a bug inside of ReadDirectoryChangesW() itself, unless it is a typo in winerror.h instead.

STATUS_NOTIFY_ENUM_DIR is used by some lower-level systems, like NT_TRANSACT_NOTIFY_CHANGE and NtNotifyChangeDirectoryFile(), to indicate that the notification data is larger than the output buffer can hold. That is what ERROR_NOTIFY_ENUM_DIR means in ReadDirectoryChangesW(), as stated in its own documentation.

Some return values of other functions, like the WaitFor...() family of functions, and OverlappedIO/IOCP functions, map directly to STATUS_... codes internally, but are not documented as such because that is a private implementation detail. For example, if you look in winbase.h, there are a couple of dozen common return codes, like WAIT_OBJECT_0, WAIT_IO_COMPLETION, STILL_ACTIVE, and various EXCEPTION_..., that map directly to STATUS_... values.

That does not appear to be the case in this situation, though. According to MSDN, STATUS_NOTIFY_ENUM_DIRis indeed supposed to map to ERROR_NOTIFY_ENUM_DIR, so this would appear to be a bug:

When a kernel-mode driver is called because of an input/output (I/O) request from the Win32 subsystem, the status code returned by the kernel- mode driver will be translated to the status code's corresponding Win32 error code. The following table shows the mapping from the Windows NT status codes to Win32 error codes.

WINDOWS NT STATUS CODE                  WIN32 ERROR CODE
------------------------------------------------------------------
...
STATUS_NOTIFY_ENUM_DIR                  ERROR_NOTIFY_ENUM_DIR
...