VSS_RESTOREMETHOD_ENUM enumeration (vswriter.h)
The VSS_RESTOREMETHOD_ENUM enumeration is used by a writer at backup time to specify through its Writer Metadata Document the default file restore method to be used with all the files in all the components it manages.
The restore method is writer-wide and is also referred to as the original restore target and indicated by a VSS_RESTORE_TARGET value of VSS_RT_ORIGINAL.
Syntax
typedef enum VSS_RESTOREMETHOD_ENUM {
VSS_RME_UNDEFINED = 0,
VSS_RME_RESTORE_IF_NOT_THERE,
VSS_RME_RESTORE_IF_CAN_REPLACE,
VSS_RME_STOP_RESTORE_START,
VSS_RME_RESTORE_TO_ALTERNATE_LOCATION,
VSS_RME_RESTORE_AT_REBOOT,
VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE,
VSS_RME_CUSTOM,
VSS_RME_RESTORE_STOP_START
} ;
Constants
VSS_RME_UNDEFINEDValue: 0 No restore method is defined. This indicates an error on the part of the writer. This value is not supported for express writers. |
VSS_RME_RESTORE_IF_NOT_THEREThe requester should restore the files of a selected component or component set only if there are no versions of those files currently on the disk. Unless alternate location mappings are defined for file restoration, if a version of any file managed by a selected component or component set is currently on the disk, none of the files managed by the selected component or component set should be restored. If a file's alternate location mapping is defined, and a version of the files is present on disk at the original location, files should be written to the alternate location only if no version of the file exists at the alternate location. |
VSS_RME_RESTORE_IF_CAN_REPLACEThe requester should restore files of a selected component or component set only if the files currently on the disk can be overwritten. Unless alternate location mappings are defined for file restoration, if there is a version of any file that cannot be overwritten of the selected component or component set on the disk, none of the files managed by the component or component set should be restored. If a file's alternate location mapping is defined, files should be written to the alternate location. |
VSS_RME_STOP_RESTORE_STARTThe requester should perform the restore operation as follows:
The service to be stopped is specified the writer beforehand when it calls the IVssCreateWriterMetadata::SetRestoreMethod method. The requester can obtain the name of the service by calling the IVssExamineWriterMetadata::GetRestoreMethod method. Note that if the writer is hosted in the service that is being stopped, that writer will not receive the PostRestore event, because the writer instance ID changes when the service is stopped and restarted. |
VSS_RME_RESTORE_TO_ALTERNATE_LOCATIONThe requester should restore the files of the selected component or component set to the location specified by the alternate location mapping specified in the writer component metadata file. (See IVssCreateWriterMetadata::AddAlternateLocationMapping, IVssComponent::GetAlternateLocationMapping, IVssExamineWriterMetadata::GetAlternateLocationMapping, and IVssWMFiledesc::GetAlternateLocation.) This value is not supported for express writers. |
VSS_RME_RESTORE_AT_REBOOTThe requester should restore the files of a selected component or component set after the computer is restarted. The files to be restored should be copied to a temporary location, and the requester should use MoveFileEx with the MOVEFILE_DELAY_UNTIL_REBOOT flag to complete the restoration of these files to their proper location after the computer is restarted. |
VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACEIf possible, the requester should restore the files of the selected component or component set to their correct location immediately. If there are versions of any of the files managed by the selected component or component set on the disk that cannot be overwritten, then all the files managed by the selected component or component set should be restored after the computer is restarted. In this case, files to be restored should be copied to a temporary location on disk, and the requester should use MoveFileEx with the MOVEFILE_DELAY_UNTIL_REBOOT flag to complete the restoration of these files to their proper location after the computer is restarted. |
VSS_RME_CUSTOMThe requester should use a custom restore method to restore the files that are managed by the selected component or component set. A custom restore may use file retrieval API functions or protocols that are private to a given writer application. Such a restore need not use the information in the writer component metadata file. (See Custom Backups and Restores for more information.) This value is not supported for express writers. |
VSS_RME_RESTORE_STOP_STARTThe requester should perform the restore operation as follows:
The service to be stopped is specified by the writer beforehand when it calls the IVssCreateWriterMetadata::SetRestoreMethod method. The requester can obtain the name of the service by calling the IVssExamineWriterMetadata::GetRestoreMethod method. |
Remarks
A writer sets the restore method in the Writer Metadata Document by calling IVssCreateWriterMetadata::SetRestoreMethod during backup to specify its desired restore method in its metadata.
A requester retrieves a writer's requested restore method by calling IVssExamineWriterMetadata::GetRestoreMethod and acts accordingly.
The restore method applies to all files in all components of a given writer.
The restore method may be overridden on a component-by-component basis at restore time if a writer sets a VSS_RESTORE_TARGET value other than VSS_RT_ORIGINAL with IVssComponent::SetRestoreTarget.
A restore method of VSS_RME_RESTORE_TO_ALTERNATE_LOCATION without an alternate location mapping defined constitutes a writer error, and the requester should report it as such.
When a restore method requires a check on the status of files currently on disk (VSS_RME_RESTORE_IF_NOT_THERE, VSS_RME_RESTORE_IF_CAN_REPLACE, or VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE), ideally, you should use file I/O operations to verify that an entire component can be restored before actually proceeding with the restore.
The safest way to do this would be to open exclusively (no-sharing) all the target files with CreateFile prior to the restore.
In the case of VSS_RME_RESTORE_IF_NOT_THERE, a creation disposition flag of CREATE_NEW should also be set.
If the open operations succeed, the restore can proceed and should use the handles returned by CreateFile to actually write restored data to disk.
If not, an error can be returned—depending on the method—or alternate location mapping checked and (if it is available) used, or the components files staged for restore at the next reboot.
This may be a problem for very large components (some of which may have thousands of files), due to system overhead.
In this case, an available though less reliable option is to do the following:
- Copy all files currently on disk and to be restored to a temporary cache.
- Attempt to replace the files currently on disk with the backed-up files (which could be either on disk in a second temporary area, or on a backup medium).
- If any files fail to restore, then terminate the restore operation and copy the original files back from their temporary location and proceed with alternate location mapping or restore on reboot operations.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Header | vswriter.h |
See also
IVssBackupComponents::AddAlternativeLocationMapping
IVssComponent::GetAlternateLocationMapping
IVssCreateWriterMetadata::AddAlternateLocationMapping
IVssCreateWriterMetadata::SetRestoreMethod
IVssExamineWriterMetadata::GetAlternateLocationMapping
IVssExamineWriterMetadata::GetRestoreMethod