SetFilePointer (Windows CE 5.0)
This function moves the file pointer of an open file. A RAPI version of this function exists, called CeSetFilePointer (RAPI).
DWORDSetFilePointer( HANDLEhFile, LONGlDistanceToMove, PLONGlpDistanceToMoveHigh, DWORDdwMoveMethod);
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
Low-order 32 bits of a signed value that specifies the number of bytes to move the file pointer. A positive value for lDistanceToMove moves the file pointer forward in the file, and a negative value moves the file pointer backward. Note that you cannot use a negative value to move back past beyond the beginning of a file. - lpDistanceToMoveHigh
Not supported; must be NULL or point to a value of zero. - dwMoveMethod
[in] Starting point for the file pointer move. The following table shows possible values for this parameter.Value Description FILE_BEGIN Indicates that the starting point is zero or the beginning of the file. FILE_CURRENT Indicates that the starting point is the current value of the file pointer. FILE_END Indicates that the starting point is the current EOF position.
Return Values
The new file pointer indicates success. If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError. However, because 0xFFFFFFFF is a valid value for the new file pointer, you must check GetLastError to determine whether an error occurred. If an error occurred, GetLastError returns a value other than NO_ERROR. For a code example that illustrates this point, see Remarks.
If the new file pointer would have been a negative value, the function fails, the file pointer is not moved, and the code returned by GetLastError is ERROR_NEGATIVE_SEEK.
Remarks
You cannot use the SetFilePointer function with a handle to a nonseeking device, such as a communications device.
You can use the SetFilePointer function to query the current file pointer position. To do this, specify a move method of FILE_CURRENT and a distance of zero.
You should be careful when setting the file pointer in a multithreaded application. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object. For more information on these objects, see Processes and Threads.
It is not an error to set the file pointer to a position beyond the end of the file. The size of the file does not increase until you call the SetEndOfFile or WriteFile function. A write operation increases the size of the file to the file pointer position plus the size of the buffer written, leaving the intervening bytes uninitialized.
If the return value is 0xFFFFFFFF, an application must call GetLastError to determine whether the function has succeeded or failed. The following code sample shows this point.
// Try to move hFile's file pointer some distance.
dwPtr = SetFilePointer (hFile, lDistance, NULL, FILE_BEGIN) ;
if (dwPtr == 0xFFFFFFFF) // Test for failure.
{
// Obtain the error code.
dwError = GetLastError() ;
// Resolve the failure.
// . . .
} // End of error handler.
Note SetFilePointer cannot be used to move the file pointer beyond the maximum file size, which is 0xFFFFFFFF. If SetFilePointer is called to move the pointer beyond 0xFFFFFFFF, the pointer is set at 0xFFFFFFFF. In this case, the return value will be 0xFFFFFFFF, but GetLastError will return NO_ERROR.
You can use SetFilePointer to determine the length of a file. To do this, use FILE_END for dwMoveMethod and seek to location zero. The file offset returned is the length of the file. However, this practice can have unintended side effects, such as failing to save the current file pointer so that the application can return to that location. It is simpler and safer to use GetFileSize.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Winbase.h.
Link Library: Coredll.lib.
See Also
CeSetFilePointer (RAPI) | GetFileSize | ReadFile | SetEndOfFile | WriteFile
Send Feedback on this topic to the authors