The ReadFile function reads data from a specified file or input/output (I/O) device. It can operate in both synchronous and asynchronous modes.
BOOL ReadFile(
HANDLE hFile,
LPVOID lpBuffer,
DWORD nNumberOfBytesToRead,
LPDWORD lpNumberOfBytesRead,
LPOVERLAPPED lpOverlapped
);
| Parameter | Description |
|---|---|
hFile |
A handle to the file or device (specified by the CreateFile function). The handle must have been created with the GENERIC_READ or GENERIC_READ | GENERIC_WRITE access right. |
lpBuffer |
A pointer to the buffer that receives the data read from the file or device. |
nNumberOfBytesToRead |
The maximum number of bytes to be read. |
lpNumberOfBytesRead |
A pointer to a 32-bit variable that receives the number of bytes actually read by the function. This parameter can be NULL if you do not need to know the number of bytes read. |
lpOverlapped |
A pointer to an OVERLAPPED structure.
This parameter is required if hFile was opened with the FILE_FLAG_OVERLAPPED flag; otherwise, it can be NULL.
If lpOverlapped is NULL, the function does not return until it has finished reading the requested number of bytes.
If lpOverlapped is not NULL, the function may return before all bytes have been read.
|
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.
The ReadFile function reads data from the file or device specified by the hFile parameter into the buffer pointed to by lpBuffer.
The read operation begins at the current file position and continues until the specified number of bytes has been read, or until the end of the file is reached.
If the file has been opened with the FILE_FLAG_OVERLAPPED flag, the read operation is performed asynchronously. In this case, ReadFile returns immediately, and the I/O operation continues in the background. The OVERLAPPED structure must contain information for the operation, including the event handle to be signaled when the operation is complete.
If the file has not been opened with FILE_FLAG_OVERLAPPED, ReadFile performs a synchronous read operation. The function does not return until the data has been read or an error occurs.
If the file handle refers to a communication resource, ReadFile operations are generally limited by the current communication timeouts set by the SetCommTimeouts function.
If the file handle refers to a message-type pipe, ReadFile reads the next message from the pipe.
If the file handle refers to a byte-type pipe or the O_NONBLOCK flag is specified, the read operation is subject to the same behavior as described for communication resources.
If the end of the file is reached before any bytes are read, the ReadFile function returns nonzero and the value pointed to by lpNumberOfBytesRead is set to zero.
If the file handle is valid and the file is open for reading, ReadFile will not fail with ERROR_INVALID_HANDLE.
Here's a basic example demonstrating how to read data from a file synchronously:
#include <windows.h>
#include <iostream>
#include <vector>
int main() {
HANDLE hFile = CreateFile(
L"example.txt", // File name
GENERIC_READ, // Desired access
FILE_SHARE_READ, // Share mode
NULL, // Security attributes
OPEN_EXISTING, // Creation disposition
FILE_ATTRIBUTE_NORMAL, // Flags and attributes
NULL); // Template file
if (hFile == INVALID_HANDLE_VALUE) {
std::cerr << "Error opening file: " << GetLastError() << std::endl;
return 1;
}
const DWORD BUFFER_SIZE = 1024;
std::vector<char> buffer(BUFFER_SIZE);
DWORD bytesRead = 0;
if (ReadFile(hFile, buffer.data(), BUFFER_SIZE - 1, &bytesRead, NULL)) {
buffer[bytesRead] = '\0'; // Null-terminate the string
std::cout << "Successfully read " << bytesRead << " bytes:" << std::endl;
std::cout << buffer.data() << std::endl;
} else {
std::cerr << "Error reading file: " << GetLastError() << std::endl;
}
CloseHandle(hFile);
return 0;
}