BackupSeek

The BackupSeek function seeks forward in a data stream initially accessed by using the BackupRead or BackupWrite function.

BOOL BackupSeek(
  HANDLE hFile,       // handle to open file
  DWORD dwLowBytesToSeek,
                      // low-order 32 bits of number of bytes
  DWORD dwHighBytesToSeek,
                      // high-order 32 bits of number of bytes
  LPDWORD lpdwLowByteSeeked,
                      // pointer to number of bytes function seeks
  LPDWORD lpdwHighByteSeeked,
                      // pointer to number of bytes function seeks
  LPVOID *lpContext   //pointer to internal context information
);
 

Parameters

hFile

Identifies the file or directory being backed up. This handle is created by using the CreateFile function.

dwLowBytesToSeek

Specifies the low-order 32 bits of the number of bytes to seek.

dwHighBytesToSeek

Specifies the high-order 32 bits of the number of bytes to seek.

lpdwLowByteSeeked

Pointer to a doubleword that, when the function returns, contains the low-order 32 bits of the number of bytes the function actually seeks.

lpdwHighByteSeeked

Pointer to a doubleword that, when the function returns, contains the high-order 32 bits of the number of bytes the function actually seeks.

lpContext

Pointer to an internal data structure used by the function. This structure must be the same structure that was initialized by the BackupRead function. An application must not touch the contents of this structure.

Return Values

If the function could seek the requested amount, the function returns nonzero.

If the function could not seek the requested amount, the function returns zero. To get extended error information, call GetLastError.

Remarks

Applications use the BackUpSeek function to skip portions of a data stream that cause errors. This function does not seek across stream headers. If an application attempts to seek past the end of a substream, the function fails, the lpdwLowByteSeeked and lpdwHighByteSeeked parameters indicate the actual number of bytes the function seeks, and the file position is placed at the start of the next stream header.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

Tape Backup Overview, Tape Backup Functions, BackupRead, BackupWrite, CreateFile