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.