Reads data from the specified file or input/output (I/O) device. It reports its completion statusasynchronously, calling the specified completion routine when reading is completed or canceled and the callingthread is in an alertable wait state.

To read data from a file or device synchronously, use theReadFile function.

Syntax

BOOL ReadFileEx(  [in]            HANDLE                          hFile,  [out, optional] LPVOID                          lpBuffer,  [in]            DWORD                           nNumberOfBytesToRead,  [in, out]       LPOVERLAPPED                    lpOverlapped,  [in]            LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);

Parameters

[in] hFile

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 theFILE_FLAG_OVERLAPPED flag by theCreateFile function, or a socket handle returned by thesocket oraccept function.

This handle also must have theGENERIC_READ access right. For more information onaccess rights, seeFile Security and Access Rights.

[out, optional] lpBuffer

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 thisbuffer until the read operation is completed.

[in] nNumberOfBytesToRead

The number of bytes to be read.

[in, out] lpOverlapped

A pointer to anOVERLAPPED data structure thatsupplies 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 theOffset andOffsetHigh members of theOVERLAPPED structure. For files or devices that do notsupport byte offsets,Offset andOffsetHigh areignored.

TheReadFileEx function ignores theOVERLAPPED structure'shEvent member. An application is free to use that member for its own purposes in thecontext of aReadFileEx call.ReadFileEx signals completion of its read operation bycalling, or queuing a call to, the completion routine pointed to bylpCompletionRoutine, so it does not need an event handle.

TheReadFileEx function does use theOVERLAPPED structure'sInternal andInternalHigh members. An application shouldnot set these members.

TheOVERLAPPED data structure must remain valid forthe duration of the read operation. It should not be a variable that can go out of scope while the readoperation is pending completion.

[in] lpCompletionRoutine

A pointer to the completion routine to be called when the read operation is complete and the calling threadis in an alertable wait state. For more information about the completion routine, seeFileIOCompletionRoutine.

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, callGetLastError.

If the function succeeds, the calling thread has an asynchronous I/O operation pending: the overlapped readoperation from the file. When this I/O operation completes, and the calling thread is blocked in an alertablewait state, the system calls the function pointed to bylpCompletionRoutine, and thewait state completes with a return code ofWAIT_IO_COMPLETION.

If the function succeeds, and the file reading operation completes, but the calling thread is not in analertable wait state, the system queues the completion routine call, holding the call until the calling threadenters an alertable wait state. For information about alertable waits and overlapped input/output operations,seeAbout Synchronization.

IfReadFileEx attempts to read past theend-of-file (EOF), the call toGetOverlappedResult for that operation returnsFALSE andGetLastErrorreturnsERROR_HANDLE_EOF.

Remarks

When usingReadFileEx you should checkGetLastError even when the function returns "success" tocheck for conditions that are "successes" but have some outcome you might want to know about. For example, abuffer overflow when callingReadFileEx will returnTRUE, butGetLastError willreport the overflow withERROR_MORE_DATA. If the function call is successful and thereare no warning conditions,GetLastError will returnERROR_SUCCESS.

TheReadFileEx function may fail if there are too manyoutstanding asynchronous I/O requests. In the event of such a failure,GetLastError can returnERROR_INVALID_USER_BUFFER orERROR_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.

UseCancelSynchronousIo to cancel pending synchronous I/O operations.

I/O operations that are canceled complete with the errorERROR_OPERATION_ABORTED.

If part of the file specified byhFile is locked by another process, and the readoperation specified in a call toReadFileEx overlaps thelocked portion, the call toReadFileEx fails.

When attempting to read data from a mailslot whose buffer is too small,ReadFileEx returnsFALSE, andGetLastError returnsERROR_INSUFFICIENT_BUFFER.

Accessing the input buffer while a read operation is using the buffer may lead to corruption of the data readinto that buffer. Applications must not read from, write to, reallocate, or free the input buffer that a readoperation is using until the read operation completes.

An application uses theMsgWaitForMultipleObjectsEx,WaitForSingleObjectEx,WaitForMultipleObjectsEx, andSleepEx functions to enter an alertable wait state. For moreinformation about alertable waits and overlapped input/output, seeAbout Synchronization.

There are strict requirements for successfully working with files opened withCreateFile usingFILE_FLAG_NO_BUFFERING. For details seeFile Buffering.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Technology	Supported
Server Message Block (SMB) 3.0 protocol	Yes
SMB 3.0 Transparent Failover (TFO)	Yes
SMB 3.0 with Scale-out File Shares (SO)	Yes
Cluster Shared Volume File System (CsvFS)	Yes
Resilient File System (ReFS)	Yes

 

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, seeAbout Transactional NTFS.

Examples

For an example, seeNamed Pipe Server Using Completion Routines.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps | UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps | UWP apps]
Target Platform	Windows
Header	fileapi.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

See also

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

File Management Functions

FileIOCompletionRoutine

MsgWaitForMultipleObjectsEx

ReadFile

SetErrorMode

SleepEx

WaitForMultipleObjectsEx

WaitForSingleObjectEx

WriteFileEx