BackupRead

Parameters

hFileHandle

Handle to file being backed up. Handle is established with CreateFile.

lpBuffer

Buffer where data stream will be placed.

dwBufferLength

Length of buffer. By definition, the buffer size must be greater than the size of a StreamID structure. The StreamID structure has the following form:

struct StreamID {

DWORD Type;

DWORD Attribute;

DWORD Size;

DWORD HighSize;

DWORD NameLength ;

CHAR Name[ ] ;

}

lpdwReturnLength

Upon return, the actual length of data placed in buffer. There is no assumption that on a given call to BackupRead that the buffer will be filled. The function may arbitrarily underfill the buffer for performance reasons. A ReturnLength of zero indicates the end of a stream has been reached. On the subsequent BackupRead call, the next stream will start at the beginning of the buffer, preceded by the appropriate stream ID.

bAbortOperation

If TRUE, then BackupRead operation is aborted, and all buffers deallocated.

lpContext

Internal context structure used only by this function.

Return Value

Returns TRUE if transfer to buffer was successful. Returns FALSE if either there is no more data to transfer (implying all streams have been processed), or an I/O error occurred during the read of the data. GetLastError should be called to determine error conditions. BackupRead processes all of the data pertaining to an opened object as a series of discrete byte streams. Each stream is preceded by a 32 bit aligned StreamID structure.

Comments

It is important that streams be processed in the same order, allowing applications to compare the data backed up against the data on the source device.

To backup and restore files, FindFirstFile and FindNextFile would be used to traverse a volume's directory tree. Files are opened in sequence. File attributes, unique file id, and number of hard links are determined. If there are hard links, the file's unique ID is saved in a table for future comparisons. The application opens a tape device \\.\Tape0 using the CreateFile function. The first time a file is encountered, the general file information is written to tape. Repeated calls to BackupRead are made, and the various streams are written to tape. The second time a file's unique ID is encountered (checked against the table only when there are hard links as above), the general file information is written, followed by only a LINK stream.

When restoring, files are opened for create, and the BackupWrite function is called with each data stream. If the stream is a LINK stream, then a hard link is established. If the data to establish a link with does not exists (a possible scenario during a selective restore), the BackupWrite fails, and the application can either use a preexisting catalog to locate and restore the original data, or more simply notify the user that the file data to be restored is located in a different location.

See Also

BackupWrite