virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom
);
Parameters
lOff
Number of bytes to move the pointer.
nFrom
Pointer movement mode. Must be one of the following values:
CFile::begin Move the file pointer lOff bytes forward from the beginning of the file.
CFile::current Move the file pointer lOff bytes from the current position in the file.
CFile::end Move the file pointer lOff bytes from the end of the file. Note that lOff must be negative to seek into the existing file; positive values will seek past the end of the file.
Return Value
If the requested position is legal, Seek returns the new byte offset from the beginning of the file. Otherwise, the return value is undefined and a CFileException object is thrown.
Remarks
The Seek function permits random access to a file's contents by moving the pointer a specified amount, absolutely or relatively. No data is actually read during the seek. If the requested position is larger than the size of the file, the file length will be extended to that position, and no exception will be thrown.
When a file is opened, the file pointer is positioned at offset 0, the beginning of the file.
Example
//example for CFile::Seek
extern CFile cfile;
LONGLONG lOffset = 1000;
ULONGLONG lActual;
lActual = cfile.Seek( lOffset, CFile::begin );
SetFilePointer
The SetFilePointer function moves the file pointer of an open file.
DWORD SetFilePointer(
HANDLE hFile, // handle to file
LONG lDistanceToMove, // bytes to move pointer
PLONG lpDistanceToMoveHigh, // bytes to move pointer
DWORD dwMoveMethod // starting point
);
Parameters
hFile
[in] Handle to the file whose file pointer is to be moved. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file.
lDistanceToMove
[in] Low-order 32 bits of a signed value that specifies the number of bytes to move the file pointer. If lpDistanceToMoveHigh is not NULL, lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value that specifies the distance to move. If lpDistanceToMoveHigh is NULL, lDistanceToMove is a 32-bit signed value. A positive value for lDistanceToMove moves the file pointer forward in the file, and a negative value moves the file pointer backward.
lpDistanceToMoveHigh
[in] Pointer to the high-order 32 bits of the signed 64-bit distance to move. If you do not need the high-order 32 bits, this pointer must be set to NULL. When non-NULL, this parameter also receives the high-order DWORD of the new value of the file pointer. For more information, see the Remarks section later in this topic.
Windows 95/98/Me: If the pointer lpDistanceToMoveHigh is not NULL, then it must point to either 0, INVALID_SET_FILE_POINTER, or the sign extension of the value of lDistanceToMove. Any other value will be rejected.
dwMoveMethod
[in] Starting point for the file pointer move. This parameter can be one of the following values. Value Meaning
FILE_BEGIN The starting point is zero or the beginning of the file.
FILE_CURRENT The starting point is the current value of the file pointer.
FILE_END The starting point is the current end-of-file position.
Return Values
If the SetFilePointer function succeeds and lpDistanceToMoveHigh is NULL, the return value is the low-order DWORD of the new file pointer. If lpDistanceToMoveHigh is not NULL, the function returns the low order DWORD of the new file pointer, and puts the high-order DWORD of the new file pointer into the LONG pointed to by that parameter.
// Case One: calling the function with lpDistanceToMoveHigh == NULL
// Try to move hFile's file pointer some distance.
dwPtr = SetFilePointer (hFile, lDistance, NULL, FILE_BEGIN) ;
if (dwPtr == INVALID_SET_FILE_POINTER) // Test for failure
{
// Obtain the error code.
dwError = GetLastError() ;
// Deal with failure.
// . . .
} // End of error handler
//
// Case Two: calling the function with lpDistanceToMoveHigh != NULL
// Try to move hFile's file pointer some huge distance.
dwPtrLow = SetFilePointer (hFile, lDistLow, & lDistHigh, FILE_BEGIN) ;
// Test for failure
if (dwPtrLow == INVALID_SET_FILE_POINTER && (dwError = GetLastError()) != NO_ERROR )
{
// Deal with failure.
// . . .
} // End of error handler
Although the parameter lpDistanceToMoveHigh is used to manipulate huge files, the value of this parameter should be set when moving files of any size. If it is set to NULL, then lDistanceToMove has a maximum value of 2^31–2, or 2 gigabytes less two. This is because all file pointer values are signed values. Therefore if there is even a small chance that the file will grow to that size, you should treat the file as a huge file and work with 64-bit file pointers. With file compression on NTFS, and sparse files, it is possible to have files that are large even if the underlying volume is not very large.
If lpDistanceToMoveHigh is not NULL, then lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value. The lDistanceToMove parameter is treated as the low-order 32 bits of the value, and lpDistanceToMoveHigh as the upper 32 bits. Thus, lpDistanceToMoveHigh is a sign extension of lDistanceToMove.
To move the file pointer from zero to 2 gigabytes, lpDistanceToMoveHigh must be set to either NULL or a sign extension of lDistanceToMove. To move the pointer more than 2 gigabytes, use lpDistanceToMoveHigh and lDistanceToMove as a single 64-bit quantity. For example, to move in the range from 2 gigabytes to 4 gigabytes set the contents of lpDistanceToMoveHigh to zero, or to –1 for a negative sign extension of lDistanceToMove.
To work with 64-bit file pointers, you can declare a LONG, treat it as the upper half of the 64-bit file pointer, and pass its address in lpDistanceToMoveHigh. This means you have to treat two different variables as a logical unit, which is error-prone. The problems can be ameliorated by using the LARGE_INTEGER structure to create a 64-bit value and passing the two 32-bit values by means of the appropriate elements of the union.
It is conceptually simpler and better design to use a function to hide the interface to SetFilePointer. To do so, use something like this: