Share via

IRAPISession::CeSetFilePointer (Windows Embedded CE 6.0)

  • Article

1/6/2010

This method moves the file pointer of an open file on a remote Windows Embedded CE–based device.

Syntax

DWORD CeSetFilePointer( 
  HANDLE hFile, 
  LONG lDistanceToMove, 
  PLONG lpDistanceToMoveHigh, 
  DWORD dwMoveMethod 
);

Parameters

  • hFile
    [in] Handle to the file for which the 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. 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] Not supported; must be NULL or point to a value of 0. .

  • 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 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 Value

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 IRAPISession::CeGetLastError and IRAPISession::CeRapiGetError.

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 IRAPISession::CeGetLastError to determine whether an error occurred. If an error occurred, IRAPISession::CeGetLastError 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 IRAPISession::CeGetLastError is ERROR_NEGATIVE_SEEK.

Remarks

You cannot use the IRAPISession::CeSetFilePointer function with a handle to a non-seeking such as communications device.

You can use the IRAPISession::CeSetFilePointer 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 multi-threaded 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 Working with 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 IRAPISession::CeSetEndOfFile or IRAPISession::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.

Requirements

Header rapi2.h
Library ole32.lib, rapiuuid.lib
Windows Embedded CE Windows Embedded CE 6.0 and later

See Also

Reference

IRAPISession
IRAPISession::CeSetEndOfFile
IRAPISession::CeWriteFile