| 术语 | readdirectorychangesw |
| 释义 | ReadDirectoryChangesW 语法： C++ BOOL WINAPI ReadDirectoryChangesW( __in HANDLE hDirectory, __out LPVOID lpBuffer, __in DWORD nBufferLength, __in BOOL bWatchSubtree, __in DWORD dwNotifyFilter, __out_opt LPDWORD lpBytesReturned, __inout_opt LPOVERLAPPED lpOverlapped, __in_opt LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine ); ReadDirectoryChangesW函数 检索资料，描述了在指定的目录的变化。该函数不向指定的目录本身的变化。 要跟踪量的变化，看到的变化期刊。 参数 hDirectory [in] 一个句柄，目录进行监测。这个目录必须打开与FILE_LIST_DIRECTORY访问权限。 Windows 2000中：只有一个句柄服务一次。额外的处理请求直到服务请求服务前完成。 lpBuffer [out] 一个DWORD指针对齐格式的缓冲区读取结果的产生办法。此缓冲区的结构是指由FILE_NOTIFY_INFORMATION结构。填充此缓冲区同步或异步，取决于如何打开目录什么价值给予lpOverlapped参数。有关详细信息，请参见备注部分。 nBufferLength [in] 该指出的是由lpBuffer参数缓冲区的字节大小。 bWatchSubtree [in] 如果此参数为TRUE，函数监测目录树在指定的目录层次。如果此参数为FALSE，函数监视器由hDirectory参数指定的目录。 dwNotifyFilter [in] 该过滤器标准的功能检查，以确定是否等待操作完成。此参数可以是一个或多个下列值。 ValueMeaning FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001Any文件在观看目录或子树名称的变更会导致更改通知等待操作返回。更改包括重命名，创建或删除文件。 FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002Any目录在观看目录或子树名称的变更会导致更改通知等待操作返回。更改包括创建或删除一个目录。 FILE_NOTIFY_CHANGE_ATTRIBUTES 在观看目录或树0x00000004Any属性的变化会导致更改通知等待操作返回。 FILE_NOTIFY_CHANGE_SIZE 0x00000008Any文件在观看目录或子树大小的变化会导致更改通知等待操作返回。作业系统检测到文件的大小改变只有当文件被写入到磁盘。对于操作系统，使用广泛的缓存，只有当检测时有足够的缓存刷新。 FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010Any改变过去写在观看目录或子树的文件时会导致更改通知等待操作返回。作业系统侦测到的变化最后写时间只有当文件被写入到磁盘。对于操作系统，使用广泛的缓存，只有当检测时有足够的缓存刷新。 FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020Any改变最后访问的文件在观看目录或子树时会导致更改通知等待操作返回。 FILE_NOTIFY_CHANGE_CREATION 0x00000040Any改变，在观看目录或子树的文件的创建时间会导致更改通知等待操作返回。 FILE_NOTIFY_CHANGE_SECURITY 0x00000100Any保安在观看目录或树描述更改导致更改通知等待操作返回。 lpBytesReturned [指出，可选] 对于同步调用，这个参数的接收到lpBuffer参数传输的字节数。对于异步调用，这个参数是不确定的。您必须使用异步通知技术，检索传输的字节数。 lpOverlapped [中，指出，可选] 对一个OVERLAPPED结构提供的数据将在异步操作中使用的指针。否则，这个值为NULL。失调和这个结构OffsetHigh成员不使用。 lpCompletionRoutine [中，可选] 一个完成例程被调用时的行动已经完成或取消，调用线程在一个可报警等待状态的指针。有关此完成例程信息，请参阅FileIOCompletionRoutine。 返回值 如果函数成功，返回值为非零。对于同步调用，这意味着操作成功。对于异步调用，这表明，这次行动是成功地排队。 如果函数失败，返回值是零。为了获得更多错误信息，调用GetLastError。 如果网络重定向器或目标文件系统不支持此操作，该函数失败，ERROR_INVALID_FUNCTION。 备注 以获取句柄到一个目录，使用国旗的FILE_FLAG_BACKUP_SEMANTICS CreateFile函数。 一个ReadDirectoryChangesW电话就可以完成同步或异步。要指定异步完成后，打开该目录CreateFile如上所述，但在另外的指定将dwFlagsAndAttributes参数FILE_FLAG_OVERLAPPED属性。然后指定一个OVERLAPPED结构当您调用ReadDirectoryChangesW。 当您第一次调用ReadDirectoryChangesW，系统分配一个缓冲区来存储变化的信息。此缓冲区，是与目录句柄，直到它关闭，它的大小不会改变在其一生。目录更改此之间发生函数调用添加到缓冲区，然后下一个调用返回。如果缓冲区溢出，缓冲区的全部内容将被丢弃和lpBytesReturned参数包含零。 在成功同步完成，lpBuffer参数是一个格式化缓冲区和写入到缓冲区的字节数可在lpBytesReturned。如果传输的字节数是零，缓冲区要么太大，为系统分配或太小，提供所有的变化，在目录或树发生的详细信息。在这种情况下，应该通过枚举计算目录或子树的变化。 异步完成后，您既可以在以下三种方式之一通知： 使用GetOverlappedResult功能。通过GetOverlappedResult收到通知，不指定参数在lpCompletionRoutine完成例程。一定要设置OVERLAPPED结构hEvent成员一个独特的事件。 使用GetQueuedCompletionStatus功能。通过GetQueuedCompletionStatus收到通知，不指定一个在lpCompletionRoutine完成例程。副处理的目录通过调用CreateIoCompletionPort函数完成端口hDirectory。 使用完成例程。要获得通过完成例行通知，用的则是完成端口没有关联的目录。指定一个lpCompletionRoutine完成例程。这个例程被调用时的操作已经完成或取消，而该线程在报警等待状态。该OVERLAPPED结构hEvent成员没有利用该系统，因此您可以使用它自己。 有关更多信息，请参阅同步和异步I / O。 ReadDirectoryChangesW失败ERROR_INVALID_PARAMETER时，缓冲区的长度大于64 KB和监测应用程序在网络上的目录。这是由于与基本的文件共享协议数据包大小限制。 ReadDirectoryChangesW缓冲区时失败不在一个DWORD边界赞同ERROR_NOACCESS。 Windows 2000中：客户端尝试多个同时长期对服务器内的要求，例如更改通知，应运行Service Pack 2或更高。详情请参阅知识库文章Q271148。 要编译的应用程序使用此函数，定义为0x0400或更高_WIN32_WINNT宏。有关详细信息，请参阅使用Windows头。 如果您打开文件使用短名称，您可以收到的短名称更改通知。 交易业务 如果绑定到一个事务处理的目录，然后通知按照适当的事务隔离规则。 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinBase.h(头文件：winuser.h) LibraryKernel32.lib DLLKernel32.dll 参见 CreateFile CreateIoCompletionPort 目录管理功能 FileIOCompletionRoutine GetOverlappedResult GetQueuedCompletionStatus FILE_NOTIFY_INFORMATION 的OVERLAPPED 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年9月3日 ＝＝英文原文＝＝ReadDirectoryChangesW Function Retrieves information that describes the changes within the specified directory. The function does not report changes to the specified directory itself. To track changes on a volume, see change journals . Syntax C++ BOOL WINAPI ReadDirectoryChangesW( __in HANDLE hDirectory, __out LPVOID lpBuffer, __in DWORD nBufferLength, __in BOOL bWatchSubtree, __in DWORD dwNotifyFilter, __out_opt LPDWORD lpBytesReturned, __inout_opt LPOVERLAPPED lpOverlapped, __in_opt LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine ); Parameters hDirectory [in] A handle to the directory to be monitored. This directory must be opened with the FILE_LIST_DIRECTORY access right. Windows 2000: Only one handle is serviced at a time. Additional handle requests are not serviced until the previous service request is completed. lpBuffer [out] A pointer to the DWORD-aligned formatted buffer in which the read results are to be returned. The structure of this buffer is defined by the FILE_NOTIFY_INFORMATION structure. This buffer is filled either synchronously or asynchronously, depending on how the directory is opened and what value is given to the lpOverlapped parameter. For more information, see the Remarks section. nBufferLength [in] The size of the buffer that is pointed to by the lpBuffer parameter, in bytes. bWatchSubtree [in] If this parameter is TRUE, the function monitors the directory tree rooted at the specified directory. If this parameter is FALSE, the function monitors only the directory specified by the hDirectory parameter. dwNotifyFilter [in] The filter criteria that the function checks to determine if the wait operation has completed. This parameter can be one or more of the following values. ValueMeaning FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001Any file name change in the watched directory or subtree causes a change notification wait operation to return. Changes include renaming, creating, or deleting a file. FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002Any directory-name change in the watched directory or subtree causes a change notification wait operation to return. Changes include creating or deleting a directory. FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004Any attribute change in the watched directory or subtree causes a change notification wait operation to return. FILE_NOTIFY_CHANGE_SIZE 0x00000008Any file-size change in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change in file size only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed. FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010Any change to the last write-time of files in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change to the last write-time only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed. FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020Any change to the last access time of files in the watched directory or subtree causes a change notification wait operation to return. FILE_NOTIFY_CHANGE_CREATION 0x00000040Any change to the creation time of files in the watched directory or subtree causes a change notification wait operation to return. FILE_NOTIFY_CHANGE_SECURITY 0x00000100Any security-descriptor change in the watched directory or subtree causes a change notification wait operation to return. lpBytesReturned [out, optional] For synchronous calls, this parameter receives the number of bytes transferred into the lpBuffer parameter. For asynchronous calls, this parameter is undefined. You must use an asynchronous notification technique to retrieve the number of bytes transferred. lpOverlapped [in, out, optional] A pointer to an OVERLAPPED structure that supplies data to be used during asynchronous operation. Otherwise, this value is NULL. The Offset and OffsetHigh members of this structure are not used. lpCompletionRoutine [in, optional] A pointer to a completion routine to be called when the operation has been completed or canceled and the calling thread is in an alertable wait state. For more information about this completion routine, see FileIOCompletionRoutine . Return Value If the function succeeds, the return value is nonzero. For synchronous calls, this means that the operation succeeded. For asynchronous calls, this indicates that the operation was successfully queued. If the function fails, the return value is zero. To get extended error information, call GetLastError . If the network redirector or the target file system does not support this operation, the function fails with ERROR_INVALID_FUNCTION. Remarks To obtain a handle to a directory, use the CreateFile function with the FILE_FLAG_BACKUP_SEMANTICS flag. A call to ReadDirectoryChangesW can be completed synchronously or asynchronously. To specify asynchronous completion, open the directory with CreateFile as shown above, but additionally specify the FILE_FLAG_OVERLAPPED attribute in the dwFlagsAndAttributes parameter. Then specify an OVERLAPPED structure when you call ReadDirectoryChangesW. When you first call ReadDirectoryChangesW, the system allocates a buffer to store change information. This buffer is associated with the directory handle until it is closed and its size does not change during its lifetime. Directory changes that occur between calls to this function are added to the buffer and then returned with the next call. If the buffer overflows, the entire contents of the buffer are discarded and the lpBytesReturned parameter contains zero. Upon successful synchronous completion, the lpBuffer parameter is a formatted buffer and the number of bytes written to the buffer is available in lpBytesReturned. If the number of bytes transferred is zero, the buffer was either too large for the system to allocate or too small to provide detailed information on all the changes that occurred in the directory or subtree. In this case, you should compute the changes by enumerating the directory or subtree. For asynchronous completion, you can receive notification in one of three ways: Using the GetOverlappedResult function. To receive notification through GetOverlappedResult, do not specify a completion routine in the lpCompletionRoutine parameter. Be sure to set the hEvent member of the OVERLAPPED structure to a unique event. Using the GetQueuedCompletionStatus function. To receive notification through GetQueuedCompletionStatus, do not specify a completion routine in lpCompletionRoutine. Associate the directory handle hDirectory with a completion port by calling the CreateIoCompletionPort function. Using a completion routine. To receive notification through a completion routine, do not associate the directory with a completion port. Specify a completion routine in lpCompletionRoutine. This routine is called whenever the operation has been completed or canceled while the thread is in an alertable wait state. The hEvent member of the OVERLAPPED structure is not used by the system, so you can use it yourself. For more information, see Synchronous and Asynchronous I/O . ReadDirectoryChangesW fails with ERROR_INVALID_PARAMETER when the buffer length is greater than 64 KB and the application is monitoring a directory over the network. This is due to a packet size limitation with the underlying file sharing protocols. ReadDirectoryChangesW fails with ERROR_NOACCESS when the buffer is not aligned on a DWORD boundary. Windows 2000: Clients that attempt multiple simultaneous long-term requests against a server, for example change notifications, should be running Service Pack 2 or higher. See Knowledge Base article Q271148 for more details. To compile an application that uses this function, define the _WIN32_WINNT macro as 0x0400 or later. For more information, see Using the Windows Headers . If you opened the file using the short name, you can receive change notifications for the short name. Transacted Operations If there is a transaction bound to the directory handle, then the notifications follow the appropriate transaction isolation rules. Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderWinBase.h (include Windows.h) LibraryKernel32.lib DLLKernel32.dll See Also CreateFile CreateIoCompletionPort Directory Management Functions FileIOCompletionRoutine GetOverlappedResult GetQueuedCompletionStatus FILE_NOTIFY_INFORMATION OVERLAPPED Send comments about this topic to Microsoft Build date: 9/3/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa365465(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。