RestoreFile function

Copies a deleted or regular file from a volume that is defined in the file restore context to a new file on an available logical drive. The volume path is set in the Volume parameter of the CreateFileRestoreContext function.

Syntax

BOOL WINAPI RestoreFile(
  _In_     PFILE_RESTORE_CONTEXT Context,
  _In_     PRESTORABLE_FILE_INFO RestorableFile,
  _In_     PCWSTR                DstFile,
  _In_opt_ FILE_RESTORE_CALLBACK Callback,
  _In_opt_ PVOID                 ClbkArg
);

Parameters

Context [in]

A pointer to the file restore context that was created by calling the CreateFileRestoreContext function.

RestorableFile [in]

A pointer to a RESTORABLE_FILE_INFO structure that specifies the file to restore that was discovered by the ScanRestorableFiles function.

DstFile [in]

The path of the destination file where the restored data will be saved.

Callback [in, optional]

The FILE_RESTORE_CALLBACK callback function to use for reporting the progress of the copying process.

ClbkArg [in, optional]

The argument to be returned with the callback function.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

This function has no associated header file or import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to fmapi.dll.

For removed files, the RestoreFile function tries to restore the file. It is possible that some of the file data might not be restored. Only data streams of the restorable file are copied, all other file information is not restored. The RestoreFile function can only be used to restore files; directories cannot be restored.

The RestoreFile function can call a callback function to report the progress of the copy process and the final status of the operation. For more information about the parameters that are used by the RestoreFile function to send information to a callback function, see the FILE_RESTORE_PACKET_TYPE enumeration.

The restore process can be canceled by returning FALSE in the callback function.

In general, FMAPI cannot guarantee the success of the restore. It uses a best-effort approach. Files that have been overwritten may not be restorable, or may be only partially restorable. In addition, limitations of the FAT file system make FMAPI inefficient in restoring fragmented files in their entirety. FMAPI will attempt to restore as much of the file as possible. In some cases, FMAPI's restored version of a file may be fully or partially corrupted (compared to the original), if the file contents and meta data were overwritten by some other file. FMAPI may not be successful in restoring very large files, due to file system restrictions.

Requirements

See also

CreateFileRestoreContext

ScanRestorableFiles