Overview of Preparing for Restore
In preparing for a restore, a requester uses the stored Writer Metadata Documents in conjunction with its own retrieved Backup Components Document to determine what is to be restored and how. For more information, see Overview of Processing a Restore Under VSS.
Following the selection of restore candidate components, writers currently running on the system access the requester's Backup Components Document. Writers use this access to indicate how to cause minimum difficulty for running services due to the restore.
After this is completed, the requester has enough information to determine which files will need to be restored, as well as where and how they should be restored. (For more information, see Generating a Restore Set.)
The following table shows the sequence of actions and events that are required to prepare for a restore operation.
| Requester action | Event | Writer action |
|---|---|---|
| Retrieve information from the Backup Components Document about the components explicitly included in the backup operation (see IVssBackupComponents::GetWriterComponents) Examine retrieved Writer Metadata Documents to get details about those components explicitly included in the backup, and any find implicitly included subcomponents. (See IVssExamineWriterMetadata, IVssWMComponent.) |
None | None |
| Select components and component sets to be restored (see IVssBackupComponents::SetSelectedForRestore and IVssBackupComponents::AddRestoreSubcomponent.) | None | None |
| The requester allows the writer to update the Backup Components Document and may optionally communicate any special restore options to the writer. (See IVssBackupComponents::SetRestoreOptions, IVssBackupComponents::AddNewTarget, and IVssBackupComponents::PreRestore.) | PreRestore | The writer determines participation in the restore, prepares files to restore, and optionally modifies Backup Components Document if necessary. (See CVssWriter::OnPreRestore, IVssComponent, IVssComponent::IsSelectedForRestore, IVssComponent::GetRestoreOptions, IVssComponent::SetRestoreTarget, IVssComponent::SetRestoreMetadata, IVssComponent::AddDirectedTarget.) |
| The requester waits on writers to handle the PreRestore event with IVssAsync. It should also verify writer status. (See IVssBackupComponents::GatherWriterStatus, IVssBackupComponents::GetWriterStatus.) | None | None |
Requester Actions during Restore Preparations
To determine which components are candidates for restore, the requester must do the following:
- Establish the component and the component set structure used to make the backup.
- Examine the components' selectability for restore.
- Use selectability guidelines (Working with Selectability for Restore and Subcomponents) to choose components to include.
- Use component file set information to determine which files on the backup media must be restored.
To do this, the requester needs to examine explicitly included components in the stored Backup Components Document. This component information is available on a writer-by-writer basis using IVssBackupComponents::GetWriterComponents, which returns instances of the IVssWriterComponentsExt interface, from which both writer information and instances of the IVssComponent interface can be retrieved.
As noted elsewhere (Use of Components by the Requester), the Backup Components Document and the IVssComponent interface do not contain enough information to support the backup. Therefore, the requester must examine the corresponding stored Writer Metadata Document by using IVssExamineWriterMetadata (see Writer Identification Information).
The number of components each writer manages is returned by IVssExamineWriterMetadata::GetFileCounts. The requester can then use IVssExamineWriterMetadata::GetComponent to get an IVssWMComponent interface for each component a writer manages.
By examining the components' selectability for backup and logical paths (see Working with Selectability and Logical Paths), a requester is able to identify the components that defined backup-time component sets (explicitly included components), and the subcomponents members of those sets (implicitly included components).
Requesters indicate through the Backup Components Document if a component is to be explicitly restored, using either IVssBackupComponents::SetSelectedForRestore or IVssBackupComponents::AddRestoreSubcomponent. The choice of method will depend on how the component was originally backed up and its selectability for restore. These components explicitly included for restore designate other components which are implicitly included (see Working with Selectability for Restore and Subcomponents for details).
A requester may explicitly include none of a currently executing writer's components for restore using IVssBackupComponents::SetSelectedForRestore or IVssBackupComponents::AddRestoreSubcomponent. In this case, that writer will not receive any VSS events for the remainder of the restore operation.
Explicitly using either IVssBackupComponents::SetSelectedForRestore or IVssBackupComponents::AddRestoreSubcomponent to select a component of a writer that is not currently running returns a VSS_E_OBJECT_NOT_FOUND error. See Restores without Writer Participation for information on restoring the data of missing writers.
To enable a writer to have complete information upon which to act, writer-specific restore options and indication of an incremental restore can be sent to the writers by requester calls to IVssBackupComponents::SetRestoreOptions and IVssBackupComponents::SetAdditionalRestores, respectively.
At this point, a requester has finished its preparation, and it generates a PreRestore event by calling IVssBackupComponents::PreRestore, allowing writers to prepare for the actual restore.
Writer Actions during Restore Preparations
Writer preparation for the restore operation occurs when handling the PreRestore event with the virtual method CVssWriter::OnPreRestore. The default implementation simply returns without taking any action. Writers may choose to override the default implementation to exercise more control by:
- Overriding restore methods with restore targets
- Defining directed targets
- Creating error messages and additional data
- Supplying backup stamp information
The event handler CVssWriter::OnPreRestore receives an instance of the IVssWriterComponents, from which it can obtain IVssComponent interfaces for those of its components explicitly included in the Backup Components Document during backup.
Information about subcomponents implicitly included in backup operations and explicitly included in restores by using an instance of the IVssComponent corresponding to the component that defined its backup component set.
The IVssComponent::IsSelectedForRestore method is used to determine whether an explicitly included for backup component is to be restored.
To determine if a backup subcomponent was explicitly included in the restore, writers use IVssComponent::GetRestoreSubcomponent.
The writer should examine the file set in each component and determine if it needs to take actions to support the restore. The writer will need to evaluate if it wants its current files overwritten, or if it will require restoration to new locations. Actions can include the following:
- Getting and acting on any writer- or requester-specific options governing restore operations (see IVssComponent::GetRestoreOptions)
- Closing and making writable any currently open files
- Updating the restore target (for instance, to force restoration to an alternate location mapping). See IVssComponent::SetRestoreTarget.
- Communicating with the requester via private metadata (see IVssComponent::SetRestoreMetadata)
- Indicating that a file should be restored by remapping through the definition of directed targets (see IVssComponent::AddDirectedTarget)
The instance of IVssComponent used will either be that created by the component's explicit inclusion in the Backup Components Document during backup, or that of the component defining the backup component set of which it was a member (see Working with Selectability For Restore and Subcomponents).