| 术语 | readfileex |
| 释义 | ReadFileEx 语法： C++ BOOL WINAPI ReadFileEx( __in HANDLE hFile, __out_opt LPVOID lpBuffer, __in DWORD nNumberOfBytesToRead, __inout LPOVERLAPPED lpOverlapped, __in_opt LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine ); ReadFileEx功能 读取指定的文件或输入数据/输出(I / O)设备。它的完成状况报告其异步调用指定的完成例程在读取完成或取消，调用线程在一个可报警等待状态。 读取文件或设备同步数据，使用ReadFile函数。 参数 hFile [in] 句柄到文件或I / O设备(例如，一个文件，文件流，物理磁盘，卷，控制台缓冲区，磁带驱动器，插座，通信资源，邮筒，或管道)。 此参数可以是任何处理由CreateFile函数，或者套接字处理套接字或接受函数返回FILE_FLAG_OVERLAPPED标志打开。 这种处理也必须有GENERIC_READ访问的权利。欲了解更多有关访问权限的信息，请参阅文件安全性和访问权限。 lpBuffer [指出，可选] 阿一个缓冲区，它接收数据指针读取文件或设备。 这个缓冲区必须保持有效的读取操作时间。应用程序不应使用之前，该缓冲区读操作完成。 nNumberOfBytesToRead [in] 的字节数被读取。 lpOverlapped [ in , out ] 一个OVERLAPPED数据结构提供的数据将在异步(重叠使用)指针文件读取操作。 对于文件，支持字节偏移，您必须指定偏移量为从文件中读取一个字节。您可以指定此偏移通过设置偏移和OVERLAPPED结构OffsetHigh成员。对于文件或设备不支持字节偏移，偏移量和OffsetHigh被忽略。 该ReadFileEx函数忽略OVERLAPPED结构的hEvent成员。应用程序是免费使用在一个ReadFileEx调用上下文自己的目的，该成员。 ReadFileEx信号调用，或排队打电话的读操作完成，完成例程指向lpCompletionRoutine，所以并不需要一个事件句柄。 该ReadFileEx函数不使用OVERLAPPED结构的内部和InternalHigh成员。一个应用程序不应该设置这些成员。 重叠数据结构必须保持有效的读取操作时间。它不应该是一个变量，可以超出了范围，而读操作有待完成。 lpCompletionRoutine [中，可选] 一个完成例程被调用时，读操作完成，并调用线程指针是在一个可报警等待状态。如需有关完成例程信息，请参阅FileIOCompletionRoutine。 返回值 如果函数成功，返回值为非零。 如果函数失败，返回值是零。为了获得更多错误信息，调用GetLastError。 如果函数成功，调用线程异步I / O操作之前：重叠从文件中读取操作。当这个I / O操作完成，并且调用线程处于可报警等待状态的封锁，系统调用函数指向lpCompletionRoutine，和等待状态的和WAIT_IO_COMPLETION返回代码完成。 如果函数成功，并读取文件操作完成，但没有调用线程在一个可报警等待状态，系统队列完成例程调用，直到举行调用调用线程进入一个可报警等待状态。有关可报警等待和重叠的输入/输出操作，请参阅关于同步信息。 如果ReadFileEx尝试读取过去的文件的末尾，该函数返回零，并GetLastError返回ERROR_HANDLE_EOF。 备注 当使用ReadFileEx您应该检查GetLastError函数甚至当函数返回的“成功”来检查的条件是“成功”，但有一些结果您可能想知道。例如，一个缓冲区溢出当调用ReadFileEx将返回TRUE，但GetLastError函数将报告与ERROR_MORE_DATA溢出。如果函数调用成功，也没有警告的条件，GetLastError函数将返回ERROR_SUCCESS。 该ReadFileEx函数可能会失败，如果有太多的异步I / O请求。在这样一个发生故障时，GetLastError函数可以返回ERROR_INVALID_USER_BUFFER或ERROR_NOT_ENOUGH_MEMORY。 要取消所有挂起的异步I / O操作，请使用： CancelIo，此功能只能取消由指定的文件句柄调用的线程发出的行动。 CancelIoEx，此功能取消了指定的文件处理线程发出的所有业务。 使用CancelSynchronousIo取消等候同步I / O操作。 I / O操作是取消与错误完全ERROR_OPERATION_ABORTED。 如果由hFile指定的文件的一部分被锁定，由另一个进程，并读取操作，以ReadFileEx调用中指定的锁定重叠部分，以ReadFileEx调用失败。 当试图从一个邮筒读的缓冲区太小数据，ReadFileEx返回FALSE，并GetLastError返回ERROR_INSUFFICIENT_BUFFER。 访问输入缓冲区读操作时使用的缓冲区可能导致数据的腐败现象，该缓冲区读取。应用程序不能读取，写入，重新分配，或免费的输入缓冲器，一个读操作，直到完成读取操作使用。 应用程序使用MsgWaitForMultipleObjectsEx，WaitForSingleObjectEx，WaitForMultipleObjectsEx，并SleepEx功能，输入一个可报警等待状态。如需有关可报警等待和重叠的输入/输出，请参阅关于同步信息。 有成功与使用FILE_FLAG_NO_BUFFERINGCreateFile打开文件的工作严格要求。详情请参阅文件缓冲。 交易业务 如果绑定到文件处理事务，那么该函数返回从文件的交易视图数据。阿交易读句柄保证显示为期限的处理文件相同的看法。有关其他信息，请参阅关于交互式NTFS。 实例 有关示例，请参见服务器使用命名管道完成例程。 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinBase.h(头文件：winuser.h) LibraryKernel32.lib DLLKernel32.dll 参见 CancelIo CancelIoEx CancelSynchronousIo CreateFile 文件管理函数 FileIOCompletionRoutine MsgWaitForMultipleObjectsEx ReadFile SetErrorMode SleepEx WaitForMultipleObjectsEx WaitForSingleObjectEx WriteFileEx 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年9月3日 ＝＝英文原文＝＝ReadFileEx Function Reads data from the specified file or input/output (I/O) device. It reports its completion status asynchronously, calling the specified completion routine when reading is completed or canceled and the calling thread is in an alertable wait state. To read data from a file or device synchronously, use the ReadFile function. Syntax C++ BOOL WINAPI ReadFileEx( __in HANDLE hFile, __out_opt LPVOID lpBuffer, __in DWORD nNumberOfBytesToRead, __inout LPOVERLAPPED lpOverlapped, __in_opt LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine ); Parameters hFile [in] A handle to the file or I/O device (for example, a file, file stream, physical disk, volume, console buffer, tape drive, socket, communications resource, mailslot, or pipe). This parameter can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept function. This handle also must have the GENERIC_READ access right. For more information on access rights, see File Security and Access Rights . lpBuffer [out, optional] A pointer to a buffer that receives the data read from the file or device. This buffer must remain valid for the duration of the read operation. The application should not use this buffer until the read operation is completed. nNumberOfBytesToRead [in] The number of bytes to be read. lpOverlapped [in, out] A pointer to an OVERLAPPED data structure that supplies data to be used during the asynchronous (overlapped) file read operation. For files that support byte offsets, you must specify a byte offset at which to start reading from the file. You specify this offset by setting the Offset and OffsetHigh members of the OVERLAPPED structure. For files or devices that do not support byte offsets, Offset and OffsetHigh are ignored. The ReadFileEx function ignores the OVERLAPPED structure's hEvent member. An application is free to use that member for its own purposes in the context of a ReadFileEx call. ReadFileEx signals completion of its read operation by calling, or queuing a call to, the completion routine pointed to by lpCompletionRoutine, so it does not need an event handle. The ReadFileEx function does use the OVERLAPPED structure's Internal and InternalHigh members. An application should not set these members. The OVERLAPPED data structure must remain valid for the duration of the read operation. It should not be a variable that can go out of scope while the read operation is pending completion. lpCompletionRoutine [in, optional] A pointer to the completion routine to be called when the read operation is complete and the calling thread is in an alertable wait state. For more information about the completion routine, see FileIOCompletionRoutine . 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 . If the function succeeds, the calling thread has an asynchronous I/O operation pending: the overlapped read operation from the file. When this I/O operation completes, and the calling thread is blocked in an alertable wait state, the system calls the function pointed to by lpCompletionRoutine, and the wait state completes with a return code of WAIT_IO_COMPLETION. If the function succeeds, and the file reading operation completes, but the calling thread is not in an alertable wait state, the system queues the completion routine call, holding the call until the calling thread enters an alertable wait state. For information about alertable waits and overlapped input/output operations, see About Synchronization . If ReadFileEx attempts to read past the end of the file, the function returns zero, and GetLastError returns ERROR_HANDLE_EOF. Remarks When using ReadFileEx you should check GetLastError even when the function returns "success" to check for conditions that are "successes" but have some outcome you might want to know about. For example, a buffer overflow when calling ReadFileEx will return TRUE, but GetLastError will report the overflow with ERROR_MORE_DATA. If the function call is successful and there are no warning conditions, GetLastError will return ERROR_SUCCESS. The ReadFileEx function may fail if there are too many outstanding asynchronous I/O requests. In the event of such a failure, GetLastError can return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY. To cancel all pending asynchronous I/O operations, use either: CancelIo —this function only cancels operations issued by the calling thread for the specified file handle. CancelIoEx —this function cancels all operations issued by the threads for the specified file handle. Use CancelSynchronousIo to cancel pending synchronous I/O operations. I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED. If part of the file specified by hFile is locked by another process, and the read operation specified in a call to ReadFileEx overlaps the locked portion, the call to ReadFileEx fails. When attempting to read data from a mailslot whose buffer is too small, ReadFileEx returns FALSE, and GetLastError returns ERROR_INSUFFICIENT_BUFFER. Accessing the input buffer while a read operation is using the buffer may lead to corruption of the data read into that buffer. Applications must not read from, write to, reallocate, or free the input buffer that a read operation is using until the read operation completes. An application uses the MsgWaitForMultipleObjectsEx , WaitForSingleObjectEx , WaitForMultipleObjectsEx , and SleepEx functions to enter an alertable wait state. For more information about alertable waits and overlapped input/output, see About Synchronization . There are strict requirements for successfully working with files opened with CreateFile using FILE_FLAG_NO_BUFFERING. For details see File Buffering . Transacted Operations If there is a transaction bound to the file handle, then the function returns data from the transacted view of the file. A transacted read handle is guaranteed to show the same view of a file for the duration of the handle. For additional information, see About Transactional NTFS . Examples For an example, see Named Pipe Server Using Completion Routines . Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderWinBase.h (include Windows.h) LibraryKernel32.lib DLLKernel32.dll See Also CancelIo CancelIoEx CancelSynchronousIo CreateFile File Management Functions FileIOCompletionRoutine MsgWaitForMultipleObjectsEx ReadFile SetErrorMode SleepEx WaitForMultipleObjectsEx WaitForSingleObjectEx WriteFileEx Send comments about this topic to Microsoft Build date: 9/3/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa365468(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。