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 file
  DWORD dwLowBytesToSeek,     // low-order DWORD of number of bytes
  DWORD dwHighBytesToSeek,    // high-order DWORD of number of bytes
  LPDWORD lpdwLowByteSeeked,  // number of bytes to forward
  LPDWORD lpdwHighByteSeeked, // number of bytes forwarded
  LPVOID *lpContext           // context information
);

Parameters

hFile

[in] Handle to the file or directory being backed up. This handle is created by using the CreateFile function.

dwLowBytesToSeek

[in] Specifies the low-order bits of the number of bytes to seek.

dwHighBytesToSeek

[in] Specifies the high-order bits of the number of bytes to seek.

lpdwLowByteSeeked

[out] Pointer to a variable that receives the low-order bits of the number of bytes the function actually seeks.

lpdwHighByteSeeked

[out] Pointer to a variable that receives the high-order bits of the number of bytes the function actually seeks.

lpContext

[in] 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 a nonzero value.

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.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

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