CeSetFilePointer (RAPI) (Windows CE 5.0)
This function moves the file pointer of an open file.
CeSetFilePointer is a remote application programming interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.
DWORDCeSetFilePointer( 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
[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 can be 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. - dwMoveMethod
[in] Specifies the starting point for the file pointer move. This parameter can be one of the following values.Value Description FILE_BEGIN The starting point is 0 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
The low-order DWORD of the new file pointer indicates success and that lpDistanceToMoveHigh is NULL. 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.
If the function fails and lpDistanceToMoveHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call CeGetLastError.
If the function fails, and lpDistanceToMoveHigh is non-NULL, the return value is 0xFFFFFFFF. However, because 0xFFFFFFFF is a valid value for the low-order DWORD of the new file pointer, you must check CeGetLastError to determine whether an error occurred. If an error occurred, CeGetLastError returns a value other than NO_ERROR. For a code example that illustrates this point, see the Remarks section later in this topic.
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 CeGetLastError is ERROR_NEGATIVE_SEEK.
Remarks
You cannot use the CeSetFilePointer function with a handle to a nonseeking such as communications device.
You can use the CeSetFilePointer function to query the current file pointer position. To do this, specify a move method of FILE_CURRENT and a distance of 0.
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 about 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 CeSetEndOfFile or CeWriteFile 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.
The parameter lpDistanceToMoveHigh is used to manipulate huge files. 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.
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 0 to 2 gigabytes, lpDistanceToMoveHigh can be 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 0, 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 CeSetFilePointer. To do so, use something like this.
__int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod)
{
LARGE_INTEGER li;
li.QuadPart = distance;
li.LowPart = CeSetFilePointer (hf, li.LowPart, &li.HighPart, MoveMethod);
if (li.LowPart == 0xFFFFFFFF && CeGetLastError() != NO_ERROR)
{
li.QuadPart = –1;
}
return li.QuadPart;
}
You can use CeSetFilePointer to determine the length of a file. To do this, use FILE_END for dwMoveMethod and seek to location 0. The file offset returned is the length of the file. However, this practice can have unintended side effects, such as failure to save the current file pointer so that the program can return to that location. It is simpler and safer to use CeGetFileSize instead.
Requirements
OS Versions: Windows CE 2.0 and later.
Header: Rapi.h.
Link Library: Rapi.lib.
See Also
RAPI Functions | CeGetFileSize | CeGetLastError | CeReadFile | CeSetEndOfFile | CeWriteFile | SetFilePointer
Send Feedback on this topic to the authors