Reads data from a specified file or input/output (I/O) device.
The ReadFile function enables you to read data from a file or device. It supports reading from files, pipes, communications resources, mailslots, and serial ports. The function can operate synchronously or asynchronously.
To read from a file, you must first open the file using the CreateFile function. The handle obtained from CreateFile is then used with ReadFile.
When reading from a file, the read operation starts at the current file pointer. After the read operation, the file pointer is advanced by the number of bytes read.
BOOL ReadFile(
HANDLE hFile,
LPVOID lpBuffer,
DWORD nNumberOfBytesToRead,
LPDWORD lpNumberOfBytesRead,
LPOVERLAPPED lpOverlapped
);
| Parameter | Type | Description |
|---|---|---|
hFile |
HANDLE |
A handle to the file or I/O device (such as a pipe). The handle must have been created with the GENERIC_READ access right.
|
lpBuffer |
LPVOID |
A pointer to the buffer that receives the data from a read operation of the file or device. |
nNumberOfBytesToRead |
DWORD |
The maximum number of bytes to be read. If this parameter is 0 and lpOverlapped is not NULL, the function may return 0 and set ERROR_IO_PENDING if the current file offset is at end of file. If this parameter is 0 and lpOverlapped is NULL, the function returns 0 and the last error is set to ERROR_SUCCESS.
|
lpNumberOfBytesRead |
LPDWORD |
A pointer to a 32-bit variable that receives the number of bytes actually read by the function.
If lpOverlapped is NULL, this parameter must be a valid pointer.
If lpOverlapped is not NULL, this parameter can be NULL. If lpOverlapped is not NULL, the NumberOfBytesRead parameter is either the total number of bytes transferred before ReadFile returns or zero if the read operation has not been completed at this time. If this value is zero and lpOverlapped is not NULL, then the read operation is still in progress. To get the transferred byte count, call GetOverlappedResult.
|
lpOverlapped |
LPOVERLAPPED |
A pointer to an OVERLAPPED structure.
If hFile is opened with FILE_FLAG_OVERLAPPED, the OVERLAPPED structure specifies the offset in the file at which to start reading.
If hFile does not have FILE_FLAG_OVERLAPPED set, the function ignores this parameter.
If hFile has FILE_FLAG_OVERLAPPED set, and this parameter is NULL, the function uses the system default offset for the file.
|
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 lpOverlapped is not NULL and the read operation is pending, the return value is zero and GetLastError returns ERROR_IO_PENDING.
If hFile is a handle to a console input buffer or to a communications device, ReadFile behaves as follows:
hFile is a console input buffer, ReadFile reads characters from the buffer into the buffer pointed to by lpBuffer. The number of bytes read is the minimum of the number of characters available and the number of bytes requested.hFile is a communications device, ReadFile reads data into the buffer pointed to by lpBuffer. The number of bytes read is the minimum of the number of bytes available and the number of bytes requested.
If hFile is opened with the FILE_FLAG_RANDOM_ACCESS or FILE_FLAG_SEQUENTIAL_SCAN flag, you can still use ReadFile to read data.
If hFile is a pipe, ReadFile blocks until enough data is available to satisfy the read request.
If the nNumberOfBytesToRead parameter is greater than the number of bytes available in the file or device, ReadFile reads only the available bytes. For example, if a file contains 10 bytes, and you request 20 bytes, ReadFile reads the 10 bytes.
If the hFile handle is valid and the lpBuffer buffer is valid, but the nNumberOfBytesToRead parameter is 0, ReadFile returns TRUE, and the value pointed to by lpNumberOfBytesRead is 0.
Asynchronous I/O
To perform an asynchronous read operation, create the file with the FILE_FLAG_OVERLAPPED attribute. Then, specify a pointer to an OVERLAPPED structure in the lpOverlapped parameter.
If the read operation is asynchronous, ReadFile may return immediately with a return value of zero and GetLastError returning ERROR_IO_PENDING. In this case, the actual read operation continues in the background. The OVERLAPPED structure must contain a valid event handle in its hEvent member. When the read operation is complete, the event is signaled.
You can retrieve the results of an asynchronous read operation using GetOverlappedResult. If the read operation is performed asynchronously, the value pointed to by lpNumberOfBytesRead is not valid until GetOverlappedResult returns.
You can also retrieve the results of an asynchronous read operation using ReadFileEx.
For more information, see Asynchronous I/O and the OVERLAPPED structure.