ReadFile Subroutine
Purpose
Reads data from a socket.
Syntax
#include <iocp.h>
boolean_t ReadFile (FileDescriptor, Buffer, ReadCount, AmountRead, Overlapped)
HANDLE FileDescriptor;
LPVOID Buffer;
DWORD ReadCount;
LPDWORD AmountRead;
LPOVERLAPPED Overlapped;
Description
The ReadFile subroutine reads the number of bytes specified by the ReadCount parameter from the FileDescriptor parameter into the buffer indicated by the Buffer parameter. The number of bytes read is saved in the AmountRead parameter. The Overlapped parameter indicates whether or not the operation can be handled asynchronously.
The ReadFile subroutine returns a boolean (an integer) indicating whether or not the request has been completed.
The ReadFile subroutine is part of the I/O Completion Port (IOCP) kernel extension.
Note: This subroutine only works to a socket file descriptor. It does
not work with files or other file descriptors.
Parameters
Item | Description |
---|---|
FileDescriptor | Specifies a valid file descriptor obtained from a call to the socket or accept subroutines. |
Buffer | Specifies the buffer from which the data will be read. |
ReadCount | Specifies the maximum number of bytes to read. |
AmountRead | Specifies the number of bytes read. The parameter is set by the subroutine. |
Overlapped | Specifies an overlapped structure indicating whether or not the request can be handled asynchronously. |
Return Values
Upon successful completion, the ReadFile subroutine returns a boolean indicating the request has been completed.
If the ReadFile subroutine is unsuccessful, the subroutine
handler performs the following functions:
- Returns a value of 0 to the calling program.
- Moves an error code, indicating the specific error, into the errno global variable. For further explanation of the errno variable, see the link in the Related Information section of this document.
Error Codes
The subroutine is unsuccessful if any of the following errors occur:
Item | Description |
---|---|
EINPROGRESS | The read request can not be immediately satisfied and will be handled asynchronously. A completion packet will be sent to the associated completion port upon completion. |
EAGAIN | The read request cannot be immediately satisfied and cannot be handled asynchronously. |
EINVAL | The FileDescriptor parameter is invalid. |
Examples
The following program fragment illustrates the use of the ReadFile subroutine
to synchronously read data from a socket:
void buffer;
int amount_read;
b = ReadFile (34, &buffer, 128, &amount_read, NULL);
The following program fragment illustrates the use of the ReadFile subroutine
to asynchronously read data from a socket:
void buffer;
int amount_read;
LPOVERLAPPED overlapped;
b = ReadFile (34, &buffer, 128, &amount_read, overlapped);
Note: The request will only be handled asynchronously if it cannot
be immediately satisfied.