MyFSD_SetFilePointer

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function moves the file position of an open file in an installable file system. The application does not call this function directly. Instead, it uses the corresponding standard Win32 function SetFilePointer. File System Disk Manager (FSDMGR) determines the file system type and calls the MyFSD_SetFilePointer implementation of the function.

Syntax

DWORD MyFSD_SetFilePointer( 
  PFILE pFile, 
  LONG lDistanceToMove, 
  PLONG pDistanceToMoveHigh, 
  DWORD dwMoveMethod
); 

Parameters

• pFile
  [in] Pointer to the value that a file system driver (FSD) passes to the FSDMGR_CreateFileHandle function when creating the file handle.

• lDistanceToMove
  [in] Low-order 32 bits of a signed value that specifies the number of bytes to move the file pointer. If this parameter is not set to NULL, the lpDistanceToMoveHigh and the lDistanceToMove form a single 64-bit signed value that specifies the distance to move. If lpDistanceToMoveHigh is set to 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.

• pDistanceToMoveHigh
  [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 may be NULL. When not NULL, this parameter also receives the high-order DWORD of the new value of the file pointer. For more information, see Remarks.

• dwMoveMethod
  [in] Starting point for the file pointer move.

  The following table shows possible 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

If the SetFilePointer function succeeds and lpDistanceToMoveHigh is set to NULL, the return value is the low-order DWORD of the new file pointer. If lpDistanceToMoveHigh is not set to 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 set to NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails, and lpDistanceToMoveHigh is not set to NULL, the return value is 0xFFFFFFFF. However, because 0xFFFFFFFF is a valid value for the low-order DWORD of the new file pointer, check GetLastError to determine whether an error occurred. If an error occurred, GetLastError returns a value other than NO_ERROR.

If the new file pointer would have been a negative value, the function fails, the file pointer is not moved, and GetLastError returns ERROR_NEGATIVE_SEEK. The following code example shows what is returned:

if (lDistanceToMove == 6)
   return 6;

Remarks

An FSD exports this function if it supports the SetFilePointer function. All FSD functions can be called on re-entry. Therefore, take this into account when developing an FSD.

FSDMGR is a DLL that manages all OS interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that supports an installable file system. The name of the DLL and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, its DLL is MyFSD.dll, and its exported functions are prefaced with MyFSD_*.

FSDMGR provides services to FSDs. The FSDMGR_RegisterVolume, the FSDMGR_CreateFileHandle, and the FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data that an FSD associates with a volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application creates a folder on a device that contains an installable file system, it calls the CreateDirectory function. FSDMGR recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the FAT file system is FATFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing FSDMGR to call FATFSD_CreateDirectoryW.

You cannot use the SetFilePointer function with a handle to a nonseeking device, such as a pipe or a communications device.

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.

If the hFile file handle was opened with the FILE_FLAG_NO_BUFFERING flag set, an application can move the file pointer only to sector-aligned positions. A sector-aligned position ** is a position that is a whole number multiple of the volume's sector size. An application can obtain a volume's sector size with the GetDiskFreeSpaceEx function. If an application calls SetFilePointer with distance-to-move values that result in a position that is not sector-aligned and a handle that was opened with FILE_FLAG_NO_BUFFERING, this function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

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 the WriteFile function. A write operation increases the size of the file to the file pointer position in addition to the size of the buffer written, leaving the intervening bytes uninitialized.

If the return value is 0xFFFFFFFF and lpDistanceToMoveHigh is not set to NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following code example shows this:

// 
// 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 == 0xFFFFFFFF) // Test for failure
{
   // Obtain the error code.
   dwError = GetLastError();
   // Resolve the failure.
} // End of error handler.
// Case Two: calling the function with lpDistanceToMoveHigh != NULL.
// Try to move hFile's file pointer some large distance.
dwPtrLow = SetFilePointer (hFile, lDistLow, & lDistHigh, FILE_BEGIN);
// Test for failure.
if (dwPtrLow == 0xFFFFFFFF && (dwError = GetLastError()) != NO_ERROR )
{
   // Resolve the failure.
} // End of error handler.

The lpDistanceToMoveHigh parameter is used to manipulate large files. If it is set to NULL, lDistanceToMove has a maximum value of 2 to the 31st power minus 2, or 2 GB minus two because all file pointer values are signed values. Therefore, if there is even a small chance that the file will grow to that size, handle the file as a large file, and work with 64-bit file pointers. With file compression on an NTFS file system and sparse files, it is possible to have files that large, even if the underlying volume is not that large.

If lpDistanceToMoveHigh ** is not set to NULL, lpDistanceToMoveHigh ** and lDistanceToMove ** form a single 64-bit signed value. The lDistanceToMove ** parameter is handled 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 GB, lpDistanceToMoveHigh ** can be set either NULL or a sign extension of lDistanceToMove. To move the pointer more than 2 GB, use lpDistanceToMoveHigh ** and lDistanceToMove ** as a single 64-bit quantity. For example, to move in the range from 2 GB to 4 GB, set the contents of lpDistanceToMoveHigh ** to zero, or to –1 for a negative sign extension of lDistanceToMove.

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 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 tje GetFileSize function.

You can also 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.

It is conceptually simpler and better design to use a function to hide the interface to SetFilePointer. The following code example shows how to implement the function:

__int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod)
{
   LARGE_INTEGER li;
   li.QuadPart = distance;
   li.LowPart = SetFilePointer (hf, li.LowPart, &li.HighPart, MoveMethod);
   if (li.LowPart == 0xFFFFFFFF && GetLastError() != NO_ERROR)
   {
      li.QuadPart = –1;
   }
   return li.QuadPart;
}

Requirements

See Also

Reference

MyFSD Functions
CreateDirectory
FSDMGR_CreateFileHandle
FSDMGR_CreateSearchHandle
FSDMGR_RegisterVolume
GetFileSize
MyFSD_ReadFile
SetFilePointer
WriteFile