| 术语 | readfile |
| 释义 | ReadFile 语法： C++ BOOL WINAPI ReadFile( __in HANDLE hFile, __out LPVOID lpBuffer, __in DWORD nNumberOfBytesToRead, __out_opt LPDWORD lpNumberOfBytesRead, __inout_opt LPOVERLAPPED lpOverlapped ); ReadFile函数 读取指定的文件或输入数据/输出(I / O)设备。发生在读取文件指针所指定的位置如果设备支持。 此功能是专为同步和异步操作。对于纯粹为异步操作设计了一个类似的功能，见ReadFileEx。 参数 hFile [in] 一个句柄，设备(例如，一个文件，文件流，物理磁盘，卷，控制台缓冲区，磁带驱动器，插座，通信资源，邮筒，或管道)。 该hFile参数必须创造了具有读访问。有关更多信息，请参阅通用访问权限和文件安全性和访问权限。 异步读操作，hFile可以是任何处理，是与由CreateFile函数，或者套接字处理套接字或接受函数返回FILE_FLAG_OVERLAPPED标志打开。 lpBuffer [out] 一个缓冲区，接收数据的指针从文件中读取或设备。 这个缓冲区必须保持有效的读取操作时间。调用者不能使用，直到该缓冲区读操作完成。 nNumberOfBytesToRead [in] 最大字节数被读取。 lpNumberOfBytesRead [指出，可选] 一个变量，它接收读取的字节数在使用同步hFile参数的指针。 ReadFile设置此值为0之前，做任何工作或错误检查。使用NULL如果这是一个异步操作，以避免潜在的错误结果这个参数。 此参数可以是NULL只有当lpOverlapped参数不是NULL。 有关详细信息，请参见备注部分。 lpOverlapped [中，指出，可选] 一个OVERLAPPED结构的指针则需要的hFile参数是与FILE_FLAG_OVERLAPPED打开，否则可以为NULL。 如果hFile与FILE_FLAG_OVERLAPPED打开的lpOverlapped参数必须指向一个有效的和独特的OVERLAPPED结构，否则，函数可以错误地报告说，读操作完成。 对于hFile，支持字节偏移，如果您使用此参数，您必须指定偏移量为从文件或设备读取一个字节。这抵消通过设置指定的偏移和OVERLAPPED结构OffsetHigh成员。对于hFile不支持字节偏移，偏移量和OffsetHigh被忽略。 如需有关lpOverlapped和FILE_FLAG_OVERLAPPED，请参见备注部分和同步和文件位置的信息条不同的组合。 返回值 如果函数成功，返回值为非零(真)。 如果函数失败，或正在完成异步返回值是零(假)。为了获得更多错误信息，调用GetLastError函数。 注意：GetLastError函数代码ERROR_IO_PENDING不是一个失败，它指定读操作尚待完成的异步。有关更多信息，请参见备注。 备注 ReadFile函数返回时，有下列情形之一发生： 该请求的字节数读取。 一个写操作完成的写管道结束。 异步处理正在使用和正在发生的异步读取。 发生错误。 如果ReadFile函数试图读取过去的文件的末尾，该函数返回零，并GetLastError返回ERROR_HANDLE_EOF。 ReadFile函数可能会失败，ERROR_INVALID_USER_BUFFER或ERROR_NOT_ENOUGH_MEMORY每当有太多的异步I / O请求。 要取消所有挂起的异步I / O操作，请使用： CancelIo，此功能只能取消由指定的文件句柄调用的线程发出的行动。 CancelIoEx，此功能取消了指定的文件处理线程发出的所有业务。 使用CancelSynchronousIo取消等候同步I / O操作。 I / O操作是取消与错误完全ERROR_OPERATION_ABORTED。 ReadFile函数可能会失败，ERROR_NOT_ENOUGH_QUOTA，这意味着调用进程的缓冲区无法锁定页面。有关其他信息，请参见SetProcessWorkingSetSize。 如果一个文件的一部分，是由另一个进程锁定和读操作锁定部分重叠，这个功能失败。 访问输入缓冲区读操作时使用的缓冲区可能导致数据的腐败现象，该缓冲区读取。应用程序不能读取，写入，重新分配，或免费的输入缓冲器，一个读操作，直到完成读取操作使用。这可以是特别问题时，使用异步文件句柄。有关更多信息，同步与异步的文件句柄可以在同步和文件位置节和发现CreateFile参考主题。 字符都可以读出控制台，使用ReadFile的句柄控制台输入输入缓冲区。控制台模式决定了ReadFile函数的确切行为。默认情况下，控制台模式ENABLE_LINE_INPUT，这表明，ReadFile改为直到达到一个回车。如果您按Ctrl + C，调用成功，但GetLastError返回ERROR_OPERATION_ABORTED。有关更多信息，请参阅CreateFile。 当从一种通讯工具，阅读，在ReadFile行为由目前的通信超时的设置和使用SetCommTimeouts和GetCommTimeouts检索功能。可能会发生不可预知的结果，如果您不设置超时值。如需有关信息通信的时间超时，请COMMTIMEOUTS。 如果ReadFile试图读取一个邮筒具有缓冲区太小，函数返回FALSE，GetLastError返回ERROR_INSUFFICIENT_BUFFER。 有成功CreateFile打开与使用FILE_FLAG_NO_BUFFERING标志档案工作的严格要求。详情请参阅文件缓冲。 如果hFile开幕时FILE_FLAG_OVERLAPPED，下列条件实际上是： 该lpOverlapped参数必须指向一个有效的和独特的OVERLAPPED结构，否则，函数可以错误地报告说，读操作完成。 在lpNumberOfBytesWritten参数应设置为NULL。使用GetOverlappedResult函数来获取的实际字节数读取。如果hFile参数与我联系/ O完成端口，您也可以由调用GetQueuedCompletionStatus函数读取的字节数。 同步和文件位置 如果hFile与FILE_FLAG_OVERLAPPED打开，它是一个异步的文件句柄，否则是同步的。使用重叠结构的规则是每一个稍有不同，如前所述。 注意：如果文件或设备是开放的异步I / O的后续调用的函数例如readfile使用该处理一般立即返回，但也表现就可以阻止执行同步。更多信息请参阅http://support.microsoft.com/kb/156932。 与异步文件处理工作的几点思考： ReadFile可能会返回读操作前完成。在这种情况下，ReadFile返回FALSE并GetLastError函数返回ERROR_IO_PENDING，允许调用进程继续在系统完成读操作。 该lpOverlapped参数必须是NULL，并应考虑到以下事实使用： 虽然活动在OVERLAPPED结构指定的设置和重置由系统自动，偏移是OVERLAPPED结构中指定不自动更新。 ReadFile重置事件一无信号状态时，它开始的I / O操作。 OVERLAPPED结构中指定的事件设置为信号状态时，读操作完成，在此之前，读取操作被认为是悬而未决。 由于读操作始于偏移量是在指定的OVERLAPPED结构和ReadFile可能会返回之前，系统读取操作Level完成(待读)，无论是抵销或任何其他部分的结构应该修改，释放，或由应用程序重复使用，直到事件发出信号(即读完成)。 如果最终文件(EOF)的过程中发现异步操作，对GetOverlappedResult呼叫该操作返回FALSE，GetLastError返回ERROR_HANDLE_EOF。 与同步的文件处理工作的几点思考： 如果lpOverlapped为NULL，则读操作始于当前文件位置和ReadFile不会返回，直到操作完成，系统更新前ReadFile返回文件指针。 如果lpOverlapped不为NULL，读取操作的偏移中指定的OVERLAPPED结构和ReadFile不会返回，直到开始读取操作完成。该系统更新前ReadFile重叠的回报所抵消。 当同步读操作到达文件末尾，ReadFile返回TRUE，并设置* lpNumberOfBytesRead为零。 有关更多信息，请参阅CreateFile和同步和异步I / O。 管道 如果一个匿名管道正在使用和写处理已经关闭，当ReadFile尝试读取使用管道的相应读处理，该函数返回FALSE，GetLastError返回ERROR_BROKEN_PIPE。 如果命名管道正在被读取的信息模式和未来的信息比nNumberOfBytesToRead参数指定时间，ReadFile返回FALSE，GetLastError返回ERROR_MORE_DATA。该邮件的其余部分可以读取后续调用了ReadFile或PeekNamedPipe功能。 如果lpNumberOfBytesRead参数为零当ReadFile返回TRUE的管道，管道的另一端被称为与nNumberOfBytesToWrite设置为零WriteFile函数。 欲了解更多有关管道信息，请管。 交易业务 如果绑定到文件处理事务，那么该函数返回从文件的交易视图数据。阿交易读句柄保证显示为期限的处理文件相同的看法。有关更多信息，请参阅关于交互式NTFS。 实例 有关代码示例，演示如何测试的最后文件，见文件末尾测试。关于其他例子，参见创建和使用读取或写入一个临时文件，并打开文件。 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinBase.h(头文件：winuser.h) LibraryKernel32.lib DLLKernel32.dll 参见 CancelIo CancelIoEx CancelSynchronousIo CreateFile 文件管理函数 GetCommTimeouts GetOverlappedResult GetQueuedCompletionStatus 的OVERLAPPED PeekNamedPipe ReadFileEx SetCommTimeouts SetErrorMode WriteFile 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年9月3日 ＝＝英文原文＝＝ReadFile Function Reads data from the specified file or input/output (I/O) device. Reads occur at the position specified by the file pointer if supported by the device. This function is designed for both synchronous and asynchronous operations. For a similar function designed solely for asynchronous operation, see ReadFileEx . Syntax C++ BOOL WINAPI ReadFile( __in HANDLE hFile, __out LPVOID lpBuffer, __in DWORD nNumberOfBytesToRead, __out_opt LPDWORD lpNumberOfBytesRead, __inout_opt LPOVERLAPPED lpOverlapped ); Parameters hFile [in] A handle to the device (for example, a file, file stream, physical disk, volume, console buffer, tape drive, socket, communications resource, mailslot, or pipe). The hFile parameter must have been created with read access. For more information, see Generic Access Rights and File Security and Access Rights . For asynchronous read operations, hFile can be any handle that is opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept function. lpBuffer [out] A pointer to the buffer that receives the data read from a file or device. This buffer must remain valid for the duration of the read operation. The caller must not use this buffer until the read operation is completed. nNumberOfBytesToRead [in] The maximum number of bytes to be read. lpNumberOfBytesRead [out, optional] A pointer to the variable that receives the number of bytes read when using a synchronous hFile parameter. ReadFile sets this value to zero before doing any work or error checking. Use NULL for this parameter if this is an asynchronous operation to avoid potentially erroneous results. This parameter can be NULL only when the lpOverlapped parameter is not NULL. For more information, see the Remarks section. lpOverlapped [in, out, optional] A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL. If hFile is opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must point to a valid and unique OVERLAPPED structure, otherwise the function can incorrectly report that the read operation is complete. For an hFile that supports byte offsets, if you use this parameter you must specify a byte offset at which to start reading from the file or device. This offset is specified by setting the Offset and OffsetHigh members of the OVERLAPPED structure. For an hFile that does not support byte offsets, Offset and OffsetHigh are ignored. For more information about different combinations of lpOverlapped and FILE_FLAG_OVERLAPPED, see the Remarks section and the Synchronization and File Position section. Return Value If the function succeeds, the return value is nonzero (TRUE). If the function fails, or is completing asynchronously, the return value is zero (FALSE). To get extended error information, call the GetLastError function. Note The GetLastError code ERROR_IO_PENDING is not a failure; it designates the read operation is pending completion asynchronously. For more information, see Remarks. Remarks The ReadFile function returns when one of the following conditions occur: The number of bytes requested is read. A write operation completes on the write end of the pipe. An asynchronous handle is being used and the read is occurring asynchronously. An error occurs. If the ReadFile function attempts to read past the end of the file, the function returns zero, and GetLastError returns ERROR_HANDLE_EOF. The ReadFile function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests. 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. The ReadFile function may fail with ERROR_NOT_ENOUGH_QUOTA, which means the calling process's buffer could not be page-locked. For additional information, see SetProcessWorkingSetSize . If part of a file is locked by another process and the read operation overlaps the locked portion, this function fails. 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. This can be particularly problematic when using an asynchronous file handle. Additional information regarding synchronous versus asynchronous file handles can be found in the Synchronization and File Position section and in the CreateFile reference topic. Characters can be read from the console input buffer by using ReadFile with a handle to console input. The console mode determines the exact behavior of the ReadFile function. By default, the console mode is ENABLE_LINE_INPUT, which indicates that ReadFile should read until it reaches a carriage return. If you press Ctrl+C, the call succeeds, but GetLastError returns ERROR_OPERATION_ABORTED. For more information, see CreateFile . When reading from a communications device, the behavior of ReadFile is determined by the current communication time-out as set and retrieved by using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the time-out values. For more information about communication time-outs, see COMMTIMEOUTS . If ReadFile attempts to read from a mailslot that has a buffer that is too small, the function returns FALSE and GetLastError returns ERROR_INSUFFICIENT_BUFFER. There are strict requirements for successfully working with files opened with CreateFile using the FILE_FLAG_NO_BUFFERING flag. For details see File Buffering . If hFile was opened with FILE_FLAG_OVERLAPPED, the following conditions are in effect: The lpOverlapped parameter must point to a valid and unique OVERLAPPED structure, otherwise the function can incorrectly report that the read operation is complete. The lpNumberOfBytesWritten parameter should be set to NULL. Use the GetOverlappedResult function to get the actual number of bytes read. If the hFile parameter is associated with an I/O completion port, you can also get the number of bytes read by calling the GetQueuedCompletionStatus function. Synchronization and File Position If hFile is opened with FILE_FLAG_OVERLAPPED, it is an asynchronous file handle; otherwise it is synchronous. The rules for using the OVERLAPPED structure are slightly different for each, as previously noted. Note If a file or device is opened for asynchronous I/O, subsequent calls to functions such as ReadFile using that handle generally return immediately, but can also behave synchronously with respect to blocked execution. For more information see http://support.microsoft.com/kb/156932 . Considerations for working with asynchronous file handles: ReadFile may return before the read operation is complete. In this scenario, ReadFile returns FALSE and the GetLastError function returns ERROR_IO_PENDING, which allows the calling process to continue while the system completes the read operation. The lpOverlapped parameter must not be NULL and should be used with the following facts in mind: Although the event specified in the OVERLAPPED structure is set and reset automatically by the system, the offset that is specified in the OVERLAPPED structure is not automatically updated. ReadFile resets the event to a nonsignaled state when it begins the I/O operation. The event specified in the OVERLAPPED structure is set to a signaled state when the read operation is complete; until that time, the read operation is considered pending. Because the read operation starts at the offset that is specified in the OVERLAPPED structure, and ReadFile may return before the system-level read operation is complete (read pending), neither the offset nor any other part of the structure should be modified, freed, or reused by the application until the event is signaled (that is, the read completes). If end-of-file (EOF) is detected during asynchronous operations, the call to GetOverlappedResult for that operation returns FALSE and GetLastError returns ERROR_HANDLE_EOF. Considerations for working with synchronous file handles: If lpOverlapped is NULL, the read operation starts at the current file position and ReadFile does not return until the operation is complete, and the system updates the file pointer before ReadFile returns. If lpOverlapped is not NULL, the read operation starts at the offset that is specified in the OVERLAPPED structure and ReadFile does not return until the read operation is complete. The system updates the OVERLAPPED offset before ReadFile returns. When a synchronous read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero. For more information, see CreateFile and Synchronous and Asynchronous I/O . Pipes If an anonymous pipe is being used and the write handle has been closed, when ReadFile attempts to read using the pipe's corresponding read handle, the function returns FALSE and GetLastError returns ERROR_BROKEN_PIPE. If a named pipe is being read in message mode and the next message is longer than the nNumberOfBytesToRead parameter specifies, ReadFile returns FALSE and GetLastError returns ERROR_MORE_DATA. The remainder of the message can be read by a subsequent call to the ReadFile or PeekNamedPipe function. If the lpNumberOfBytesRead parameter is zero when ReadFile returns TRUE on a pipe, the other end of the pipe called the WriteFile function with nNumberOfBytesToWrite set to zero. For more information about pipes, see Pipes . 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 more information, see About Transactional NTFS . Examples For a code example that shows you how to test for end-of-file, see Testing for the End of a File . For other examples, see Creating and Using a Temporary File and Opening a File for Reading or Writing . 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 GetCommTimeouts GetOverlappedResult GetQueuedCompletionStatus OVERLAPPED PeekNamedPipe ReadFileEx SetCommTimeouts SetErrorMode WriteFile Send comments about this topic to Microsoft Build date: 9/3/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa365467(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。