ReadFile Function

Declare Function ReadFile Lib "kernel32.dll" (ByVal hFile As Long, lpBuffer As Any, ByVal nNumberOfBytesToRead As Long, lpNumberOfBytesRead As Long, lpOverlapped As Any) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

ReadFile reads the desired amount of bytes from a file. The file must of course have been opened with at least read-level access. If the file is synchronous (not overlapped), the function begins reading the file from the current position of the file pointer, and the function automatically adjusts the file pointer to point to the byte immediately after the last byte read. If the file is asynchronous (overlapped), the structure passed as lpOverlapped identifies the point to begin reading from, and the program calling the function is responsible for updating the file pointer.

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful (including if the function attempted to read past the end of the file), the function returns a non-zero value.

Visual Basic-Specific Issues

When passing a string as lpBuffer to receive the data read from the file, the ByVal keyword must preceed the string. The keyword is not necessary for any other data types passed for lpBuffer. When passing 0 for lpOverlapped, the expression ByVal CLng(0) must be used.

Parameters

hFile: A handle to the file to read from. The file must have at least read-level access.
lpBuffer: The variable, array, or structure which receives the data read from the file.
nNumberOfBytesToRead: The number of bytes of data to read from the file and put into lpBuffer.
lpNumberOfBytesRead: Receives the number of bytes of data actually read from the file. If this is less than lpNumberOfBytesToRead, the function has attempted to read beyond the end of the file.
lpOverlapped: If the file is asynchronous (overlapped), this is an OVERLAPPED structure specifying where to begin reading from. If the file is synchronous (not overlapped), this must be 0.

Example

' This code is licensed according to the terms and conditions listed here.

' Read both a Long (32-bit) number and a String from the file
' C:\Test\myfile.txt.  Notice how the ByVal keyword must be used
' when reading a string variable.
Dim longbuffer As Long  ' receives long read from file
Dim stringbuffer As String  ' receives string read from file
Dim numread As Long  ' receives number of bytes read from file
Dim hFile As Long  ' handle of the open file
Dim retval As Long  ' return value

' Open the file for read-level access.
hFile = CreateFile("C:\Test\myfile.txt", GENERAL_READ, FILE_SHARE_READ, ByVal CLng(0), OPEN_EXISTING, FILE_ATTRIBUTE_ARCHIVE, 0)
If hfile = -1 Then  ' the file could not be opened
  Debug.Print "Unable to open the file -- it probably does not exist."
  End  ' abort the program
End If

' Read a Long-type number from the file
retval = ReadFile(hFile, longbuffer, Len(longbuffer), numread, ByVal CLng(0))
If numread < Len(longbuffer) Then  ' EOF reached
  Debug.Print "End of file encountered -- could not read the data."
Else
  Debug.Print "Number read from file:"; longbuffer
End If

' Read a 10-character string from the file
stringbuffer = Space(10)  ' make room in the buffer
retval = ReadFile(hFile, ByVal stringbuffer, 10, numread, ByVal CLng(0))
If numread = 0 Then  ' EOF reached
  Debug.Print "End of file encountered -- could not read any data."
ElseIf numread < 10 Then  ' read between 0 and 10 bytes
  Debug.Print "Incomplete string read: "; Left(stringbuffer, numread)
Else
  Debug.Print "String read from file: "; stringbuffer
End If

' Close the file.
retval = CloseHandle(hFile)