SetFilePointer Function

Declare Function SetFilePointer Lib "kernel32.dll" (ByVal hFile As Long, ByVal lDistanceToMove As Long, lpDistanceToMoveHigh As Long, ByVal dwMoveMethod As Long) 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

SetFilePointer changes the position of the file pointer in an open file. The pointer can be moved either forwards or backwards relative to the beginning of the file, the current file pointer position, or the end of the file. The file pointer cannot be moved more than one byte past the last byte of the file (where it would point to the end of the file).

When calculating the value for lDistanceToMove and the value to set the variable passed as lpDistanceToMoveHigh for negative numbers (i.e., moving the file pointer backwards), you cannot simply take the negative of the absolute value. First put the absolute values into those parameters. For lpDistanceToMoveHigh, perform a bitwise NOT operation on the value. For lDistanceToMove, perform a bitwise NOT operation followed by adding 1. See the example for a demonstration of this procedure, which is necessary to product a 64-bit negative number from a composite of the two dwords.

Return Value

If successful, the function returns the low-order dword of the new file pointer position. The high-order dword of the file pointer position is placed into the variable passed as lpDistanceToMoveHigh. If an error occured, the function returns -1 (use GetLastError to get the error code).

Visual Basic-Specific Issues

None.

Parameters

hFile

A handle to the open file to move the file pointer of.

lDistanceToMove

The low-order dword of the 64-bit integer identifying the number of bytes to move the file pointer. For negative values, consult the second paragraph under Description & Usage above.

lpDistanceToMoveHigh

Variable that contains the high-order dword of the 64-bit integer identifying the number of bytes to move the file pointer. For negative values, consult the second paragraph under Description & Usage above. After the call, the variable receives the high-order dword of the new file pointer.

dwMoveMethod

One of the following flags specifying the reference point to move the file pointer from:

FILE_BEGIN: The beginning of the file; i.e., the very first byte of the file.
FILE_CURRENT: The current position of the file pointer.
FILE_END: The end of the file; i.e., immediately after the very last byte of the file.

Constant Definitions

Const FILE_BEGIN = 0
Const FILE_CURRENT = 1
Const FILE_END = 2

Example

Read two four-character strings from the file "C:\Test\myfile.txt": one string starting at the third byte from the beginning, and the other starting five bytes from the end. To use this example, place a command button named Command1 on a form window.

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

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Declare Function CreateFile Lib "kernel32.dll" Alias "CreateFileA" (ByVal lpFileName As String, _
	ByVal dwDesiredAccess As Long, ByVal dwShareMode As Long, lpSecurityAttributes As Any, _
	ByVal dwCreationDisposition As Long, ByVal dwFlagsAndAttributes As Long, ByVal hTemplateFile _
	As Long) As Long
Public Const GENERIC_READ = &H80000000
Public Const FILE_SHARE_READ = &H1
Public Const OPEN_EXISTING = 3
Public Const FILE_ATTRIBUTE_ARCHIVE = &H20
Public Declare Function SetFilePointer Lib "kernel32.dll" (ByVal hFile As Long, ByVal lDistanceToMove _
	As Long, lpDistanceToMoveHigh As Long, ByVal dwMoveMethod As Long) As Long
Public Const FILE_BEGIN = 0
Public Const FILE_END = 2
Public 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
Public Declare Function CloseHandle Lib "kernel32.dll" (ByVal hObject As Long) As Long

' *** Place the following code inside the form window. ***

Private Sub Command1_Click()
	Dim strbuf As String * 4  ' receives four-byte string from the file
	Dim lowbyte As Long       ' low dword of file pointer position
	Dim highbyte As Long      ' high dword of file pointer position
	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, if it already exists.
	hFile = CreateFile("C:\Test\myfile.txt", GENERAL_READ, FILE_SHARE_READ, ByVal CLng(0), _
		OPEN_EXISTING, FILE_ATTRIBUTE_ARCHIVE, 0)
	If hFile = -1 Then
		Debug.Print "Unable to open the file -- it probably does not exist."
		Exit Sub
	End If
	
	' Keep in mind that, although the lpDistanceToMoveHigh parameter
	' must be passed a variable, the lDistanceToMove parameter can be
	' passed either a variable or a literal constant.  For clarity, the
	' following code uses a variable for lDistanceToMove.
	
	' Set the file pointer to 2 bytes after the beginning of the file -- i.e., the third byte position.
	lowbyte = 2
	highbyte = 0
	lowbyte = SetFilePointer(hFile, lowbyte, highbyte, FILE_BEGIN)
	' Now read four characters and display them.
	retval = ReadFile(hFile, ByVal strbuf, 4, numread, ByVal CLng(0))
	Debug.Print "Four-character string starting at byte 3: "; strbuf
	
	' Set the file pointer to 5 bytes before the beginning of the file.  Note how the lowbyte 
	' and highbyte numbers must be manipulated to represent a negative value.
	lowbyte = (Not 5) + 1
	highbyte = Not 0
	lowbyte = SetFilePointer(hFile, lowbyte, highbyte, FILE_END)
	' Now read four characters from here and display them.
	retval = ReadFile(hFile, ByVal strbuf, 4, numread, ByVal CLng(0))
	Debug.Print "Four-character string starting at the fifth byte from the end: "; strbuf
	
	' Close the file.
	retval = CloseHandle(hFile)
End Sub