| BOOL ReadFileEx(hFile, lpBuffer, nNumberOfBytesToRead, lpOverlapped, lpcr) | |||||
| HANDLE hFile; | /* file to read | */ | |||
| LPVOID lpBuffer; | /* address of buffer | */ | |||
| DWORD nNumberOfBytesToRead; | /* bytes to read | */ | |||
| LPOVERLAPPED lpOverlapped; | /* contains offset | */ | |||
| LPOVERLAPPED_COMPLETION_ROUTINE lpcr; | |||||
The ReadFileEx function reads data from a file and reports its completion status asynchronously.
This function is available only in Win32/NT.
hFile
Identifies the file to read from. The file handle must have been created with the FILE_FLAG_OVERLAPPED flag and must have GENERIC_READ access to the file.
lpBuffer
Points to the buffer to receive the data read from the file.
nNumberOfBytesToRead
Specifies the number of bytes to read from the file.
lpOverlapped
Points to an OVERLAPPED structure. This structure must remain valid for the entire duration of the read operation; it should not be a local variable if the calling application can return while the read operation is still pending.
The OVERLAPPED structure has the following form:
typedef struct _OVERLAPPED { /* o */
DWORD Internal;
DWORD InternalHigh;
DWORD Offset;
DWORD OffsetHigh;
HANDLE hEvent;
} OVERLAPPED;
typedef OVERLAPPED *LPOVERLAPPED;
lpcr
Points to the completion routine that will be called when the read operation completes. For more information on the completion routine, see the description of the FileIOCompletionRoutine function.
The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.
The function returns TRUE if the read operation has not yet completed. If the calling thread is in an alertable wait (using the SleepEx, WaitForSingleObjectEx or WaitForMultipleObjectsEx functions) when the read operation completes, the completion routine is called and the wait completes with a return value of WAIT_IO_COMPLETION.
If the calling thread is not in an alertable wait when the read operation completes, Win32 queues the completion routine call until the thread enters an alertable wait.
If ReadFileEx attempts to read past the end of the file, the function fails and GetLastError returns ERROR_HANDLE_EOF.
This function will fail if part of the file is locked by another process and the read overlaps the locked portion.
See the WriteFileEx function reference for sample code using asynchronous file I/O.
CreateFile, ReadFile, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx