ScanRestorableFiles function
Searches for files that are available to be restored. The behavior of this function depends on the Flags parameter of the CreateFileRestoreContext function.
Note
FMAPI can only be used in the Windows Preinstallation Environment (WinPE) for Windows Vista, Windows Server 2008, and later. Applications that use FMAPI must license WinPE.
Syntax
BOOL WINAPI ScanRestorableFiles(
_In_ PFILE_RESTORE_CONTEXT Context,
_In_ PCWSTR Path,
_In_ ULONG FileInfoSize,
_Out_ PRESTORABLE_FILE_INFO FileInfo,
_Out_ PULONG FileInfoUsed
);
Parameters
-
Context [in]
-
A pointer to the file restore context created using the CreateFileRestoreContext function.
-
Path [in]
-
The initial path of where to begin the scan for files to restore.
-
FileInfoSize [in]
-
The size of the buffer that contains the RESTORABLE_FILE_INFO structure to which the FileInfo parameter points, in bytes.
-
FileInfo [out]
-
A pointer to a RESTORABLE_FILE_INFO structure that contains information about the file or directory to be restored.
-
FileInfoUsed [out]
-
A pointer to a variable that contains the length of the RESTORABLE_FILE_INFO structure or specifies the required space for the structure.
Return value
If the function succeeds, returns TRUE.
If the function fails, returns FALSE. To get extended error information, call the GetLastError function.
If TRUE is returned, the RESTORABLE_FILE_INFO structure that is pointed to by the FileInfo parameter contains information about the file or directory to be restored.
If FALSE is returned and the value of FileInfoSize is less than the value that the FileInfoUsed parameter points to, the buffer is too small. GetLastError returns ERROR_INSUFFICIENT_BUFFER.
When scanning is complete, FALSE is returned and GetLastError returns ERROR_NO_MORE_FILES.
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.
Typically, scanning is performed to discover files that have been removed. To discover files that have been removed, the FlagScanRemovedFiles flag must be set in the Flags parameter of the CreateFileRestoreContext function. If the FlagScanIncludeRemovedDirectories flag is also set, the scan includes both files and directories.
Sometimes it is necessary to restore regular files on lost volumes. To scan for regular files, the FlagScanRegularFiles flag must be set in the Flags parameter of the CreateFileRestoreContext function.
The ScanRestorableFiles function populates the RESTORABLE_FILE_INFO structure for one file or directory that is found on the volume. To restore multiple files or directories, the ScanRestorableFiles function must be called for each file or directory that you want to discover.
The RESTORABLE_FILE_INFO structure can be variable in size. To determine the size that is required for the structure, the ScanRestorableFiles function should be called the first time with the FileInfoSize parameter set to zero. The ScanRestorableFiles function returns the required size of the RESTORABLE_FILE_INFO structure in the FileInfoUsed parameter. If subsequent calls to the ScanRestorableFiles function return FALSE, the value in the FileInfoUsed parameter is greater than the value in the FileInfoSize parameter, and GetLastError returns ERROR_INSUFFICIENT_BUFFER, this means that there is not enough space and the FileInfo buffer must be expanded. After the buffer has been expanded, the scan can be resumed with the same file restore context without the loss of data.
ScanRestorableFiles's scanning process uses a find-first, find-next mechanism for finding files. The first time ScanRestorableFiles is called, the Path parameter is used to find the first restorable file. Each subsequent call to ScanRestorableFiles ignores the Path parameter and searches for the next file. The scan process cannot be restarted from the beginning with an existing file restore context. To restart the scan process, call the CloseFileRestoreContext function, and then create a new file restore context using the CreateFileRestoreContext function.
If a restorable file is found, each call to ScanRestorableFiles returns a RESTORABLE_FILE_INFO in the FileInfo parameter that references the restorable file or a partial path to the restorable file. Check the IsRemoved member of the RESTORABLE_FILE_INFO structure to determine whether the file returned is restorable.
Requirements
| Minimum supported client |
Windows Vista [desktop apps only] |
| Minimum supported server |
Windows Server 2008 [desktop apps only] |
| DLL |
|