ZwNotifyChangeDirectoryFileEx routine

The ZwNotifyChangeDirectoryFileEx routine monitors a directory file for changes. Once a change is made to the directory specified by the FileHandle parameter, the I/O operation is completed.

Syntax

NTSTATUS ZwNotifyChangeDirectoryFileEx(
  _In_     HANDLE                             FileHandle,
  _In_opt_ HANDLE                             Event,
  _In_opt_ PIO_APC_ROUTINE                    ApcRoutine,
  _In_opt_ PVOID                              ApcContext,
  _Out_    PIO_STATUS_BLOCK                   IoStatusBlock,
  _Out_    writes_bytes_(Length) PVOID        Buffer,
  _In_     ULONG                              Length,
  _In_     ULONG                              CompletionFilter,
  _In_     BOOLEAN                            WatchTree,
  _In_opt_ DIRECTORY_NOTIFY_INFORMATION_CLASS DirectoryNotifyInformationClass
);

Parameters

• FileHandle [in]
  A handle returned by ZwCreateFile or ZwOpenFile for the file object whose Extended Attributes (EA) should be changed. The file object must have been opened for asynchronous I/O if the caller specifies a non-NULL value for Event or ApcRoutine.

• Event [in, optional]
  An optional handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the requested operation is completed and the given event is set to the Signaled state. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.

• ApcRoutine [in, optional]
  A pointer to an optional, caller-supplied Asynchronous Procedure Call (APC) routine to be called when the requested operation completes. This parameter is optional and can be NULL. If there is an I/O completion object associated with the file object, this parameter must be NULL.

• ApcContext [in, optional]
  An optional pointer to a context parameter to be passed to the ApcRoutine, if an ApcRoutine was specified.

  This parameter is optional and can be NULL. It must be NULL if ApcRoutine is NULL and there is no I/O completion object associated with the file object.

• IoStatusBlock [out]
  A pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation. For successful calls that return data, the number of bytes written to the FileInformation buffer is returned in the structure's Information member.

• Buffer [out]
  A pointer to a buffer that receives the names of the files or directories that have changed since the last time that this routine was called.

• Length [in]
  The size, in bytes, of the buffer pointed to by Buffer. On the initial call, this parameter also specifies how large to make the system's internal buffer. Specifying a buffer length of zero causes the request to complete when changes are made, but no information about the changes are returned.

• CompletionFilter [in]
  Specifies the types of changes to files or directories within the directory that will complete the I/O operation.

• WatchTree [in]
  Indicates whether or not changes to directories below the directory referred to by the FileHandle parameter cause the operation to complete.

• DirectoryNotifyInformationClass [in, optional]
  Specifies the information class that the caller needs. DirectoryNotifyInformationClass contains one of the following values:

  Value	Meaning
  DirectoryNotifyInformation	The caller needs a FILE_NOTIFY_INFORMATION structure.
  DirectoryNotifyExtendedInformation	The caller needs a FILE_NOTIFY_EXTENDED_INFORMATION structure.

   

Return value

The ZwQueryDirectoryFileExroutine returns STATUS_SUCCESS if the query operation was properly queued to the I/O system. Once the operation completes, the status of the query can be determined by examining the Status field of the I/O status block.

Requirements

Send comments about this topic to Microsoft