ReadFile (Windows CE 5.0)

Article
09/14/2012

This function reads data from a file, starting at the position indicated by the file pointer. After the read operation has been completed, the file pointer is adjusted by the number of bytes actually read.

BOOLReadFile( HANDLEhFile, LPVOIDlpBuffer, DWORDnNumberOfBytesToRead, LPDWORDlpNumberOfBytesRead, LPOVERLAPPEDlpOverlapped);

Parameters

hFile
[in] Handle to the file to be read. The file handle must have been created with GENERIC_READ access to the file. This parameter cannot be a socket handle.
lpBuffer
[out] Pointer to the buffer that receives the data read from the file.
nNumberOfBytesToRead
[in] Number of bytes to be read from the file.
lpNumberOfBytesRead
[out] Pointer to the number of bytes read. ReadFile sets this value to zero before taking action or checking errors.
lpOverlapped
[in] Unsupported; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

If the return value is nonzero and the number of bytes read is zero, the file pointer was beyond the current end of the file at the time of the read operation.

Remarks

If part of the file is locked by another process and the read operation overlaps the locked portion, this function fails.

Accessing the input buffer while a read operation is using the buffer may lead to corruption of the data read into that buffer. Applications must not read from, write to, reallocate, or free the input buffer that a read operation is using until the read operation completes.

When reading from a communications device, the behavior of ReadFile is governed by the current communication time-outs as set and retrieved using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the time-out values. For more information on communication time-outs, see COMMTIMEOUTS.

The ReadFile function may fail and return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

When a read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero. Windows CE does not support asynchronous read operations on files. The following code sample shows a test for end-of-file.

// Attempt a synchronous read operation. 
bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, NULL) ; 
// Check for end of file. 
if (bResult &&  (nBytesRead == 0) ) 
{ 
    // you are at the end of the file. 
}

Windows Mobile Remarks

You should not access files with the attribute FILE_ATTRIBUTE_ROMMODULE as normal files. Although the CreateFile function will succeed on these files, reading the contents or accessing the contents of the file through file mapping will return unexpected data.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Winbase.h.
Link Library: Coredll.lib.