CreateFileRestoreContext function
Initializes the context that is used to restore files. The context can be created for an existing recognized volume or for a lost (unrecognized) volume.
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 CreateFileRestoreContext(
_In_ PCWSTR Volume,
_In_ RESTORE_CONTEXT_FLAGS Flags,
_In_opt_ LONGLONG StartSector,
_In_ LONGLONG BootSector,
_In_ DWORD Version,
_Out_ PFILE_RESTORE_CONTEXT Context
);
Parameters
-
Volume [in]
-
The path of the volume or physical drive to be used.
To specify a physical drive, use the following syntax: "\\.\PhysicalDriveN", where N is a valid drive number, for example, "\\.\PhysicalDrive0".
To specify a mounted volume, use the following syntax: "\\.\N:", where N is a valid drive letter, for example, "\\.\C:".
If Flags is set to ContextFlagVolume, this parameter identifies a volume. If Flags is set to ContextFlagDisk, this parameter identifies a physical drive.
-
Flags [in]
-
The type of context that is created. The value of this parameter can be a combination of constants from the RESTORE_CONTEXT_FLAGS enumeration.
-
StartSector [in, optional]
-
If Flags contains ContextFlagDisk, this parameter specifies the first sector offset of the lost volume. If Flags does not contain ContextFlagDisk, this parameter is ignored.
-
BootSector [in]
-
If Flags contains ContextFlagDisk, this parameter specifies the boot sector offset of the lost volume. The value of this parameter can be the same as the value of StartSector or it can be the last volume sector.
-
Version [in]
-
The major and minor version number. This parameter must match the version of FMAPI that is being used, according to the following table.
Value Meaning - FILE_RESTORE_VERSION_1
Windows 7, Windows Server 2008 R2, Windows Server 2008, and Windows Vista - FILE_RESTORE_VERSION_2
Windows 8 and Windows Server 2012 -
Context [out]
-
A PFILE_RESTORE_CONTEXT pointer to save the file restore context.
Return value
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error information, call GetLastError.
If the Version parameter does not match the version of FMAPI that is being used, this function returns FALSE, and GetLastError returns ERROR_INVALID_PARAMETER.
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.
If Flags contains ContextFlagVolume, the CreateFileRestoreContext function uses the FSCTL_LOCK_VOLUME control code to lock the volume.
If the files to be restored are encrypted with BitLocker, the CreateFileRestoreContext function does one of the following:
- On Windows 8 and Windows Server 2012 (FMAPI version 2),
- On Windows 7, Windows Server 2008 R2, and Windows Server 2008, if Flags contains ContextFlagDisk, the CreateFileRestoreContext function tries to retrieve all of the required BitLocker key information from the disk and the Trusted Platform Module (TPM). If the necessary information for BitLocker decryption is not available, the file restore context is created with minimal validation. In such cases, you must call the SupplyDecryptionInfo function to provide the restore context with the keys that are needed to perform data decryption. Supplying this information is required only if BitLocker setup was completed with an external startup-key file on a USB drive without using a TPM. The call to the SupplyDecryptionInfo function must be completed before any call to ScanRestorableFiles or RestoreFile.
- On Windows Vista, if Flags contains ContextFlagVolume, the function succeeds only if the volume is unlocked by BitLocker. If the volume is not unlocked, the function returns an error.
Requirements
| Minimum supported client |
Windows Vista [desktop apps only] |
| Minimum supported server |
Windows Server 2008 [desktop apps only] |
| DLL |
|