Generating A Restore Set

A restore set is a list of all files to be restored and the locations to which they will be restored.

As when generating the backup file list (see Generating A Backup Set), an algorithm for determining which files to restore and where to restore them must proceed writer instance by writer instance, and on a component-by-component basis for each writer instance.

It is necessary to associate each file on the backup media with the component that managed it. It is also necessary to obtain the managing component's restore method, and the file's restore target information, and its alternate location mappings (if any).

Some files may also require partial files operations or directed targets for restore.

By examining the components' selectability for backup and logical paths (see Working with Selectability and Logical Paths), a requester is able to determine the component structure of the backup operation it is going to restore.

With the component structure of the backup established, the requester can get each component's file set information (file specification, path, and recursion flag). A requester can then generate a restore set.

Files requiring partial files, or directed targets provide their own detailed restoration instructions (see Non-Default Backup and Restore Locations), which can then be added to the restore set.

A typical mechanism for generating a restore set for files not involved with partial files operations, or directed targets might proceed by doing the following:

1. Obtain a list of files on the backup media, including their original paths.

2. Identify the writer class and component for each file on the backup media by doing the following:

   • For each writer, obtain component information (IVssWMComponent) by calling IVssExamineWriterMetadata::GetComponent on all its components.

   • For each component, obtain file descriptor (IVssWMFiledesc) information for every set of files the component contains (depending on the types of data the component contains by calling IVssWMComponent::GetFile, IVssWMComponent::GetDatabaseFile, and IVssWMComponent::GetDatabaseLogFile.

   • Compare the file's name and path information against that returned by the path information contained in the file descriptor for each set of files in a component (returned by IVssWMFiledesc::GetPath, IVssWMFiledesc::GetFilespec, and IVssWMFiledesc::GetRecursive) against stored files path information to determine whether the file is part of the component.

     Note

     You should ignore any alternate location information in the file descriptor retrieved from a component found in a stored Writer Metadata Document (that is, IVssWMFiledesc::GetAlternateLocation does not return NULL). This alternate location is the alternate path, which is used only during backup.

      

3. Obtain alternate mapping information for each file on the backup media:

   • Alternate file mappings are stored at the writer, not the component level, and are obtained from the object IVssWMFiledesc returned by IVssExamineWriterMetadata::GetAlternateLocationMapping.
   • You can determine if a particular file has an alternate location mapping by checking the file's path and name against the path and file specification contained in the alternate location mapping returned by IVssExamineWriterMetadata::GetAlternateLocationMapping, via IVssWMFiledesc::GetPath, IVssWMFiledesc::GetFilespec, and IVssWMFiledesc::GetRecursive. (If an alternate path was used during backup, that information should be ignored during this check in processing a restore.)
   • If a file and an alternate location mappings file descriptors match, you then use the IVssWMFiledesc::GetAlternateLocation method of the IVssWMFiledesc object returned by IVssExamineWriterMetadata::GetAlternateLocationMapping to find the alternate location to which you can restore the file.
   • The alternate location mapping obtained in this way will not necessarily agree with that returned from the Backup Components Document by IVssComponent::GetAlternateLocationMapping. The IVssWMFiledesc::GetAlternateLocation value is nonblank only if the alternate location mapping is used for a file.

4. With this file and component information, the Backup Components Document can be queried to obtain information about restore targets, options, and new restore locations for each file. This information can be combined with the list of files, components, and alternate locations.

5. Files not protected by writers can be selected in a manner consistent with traditional restore operations.

At this point, a requester should have a list of all the files it needs to restore, along with instructions about how to restore them, and can begin restoring files on the basis of:

• Whether alternate location mappings, or the original file location is to be used as the target for the restore will depend on the presence or absence of a file at that target location and component settings of VSS_RESTORE_TARGET and VSS_RESTOREMETHOD_ENUM (see Non-Default Backup and Restore Locations).
• Whether an attempt at restoration succeeds will depend on issues such as the access permissions of the target, if target files are locked, and other conventional issues involved in file restoration.
• The success or failure of restoring a given component for a given writer instance should be preserved in the Backup Components Document by calling IVssBackupComponents::SetFileRestoreStatus. This will make the information accessible to writers when they process the PostRestore event.
• If a file is restored to an alternate location mapping, the requester must call IVssBackupComponents::AddAlternativeLocationMapping. This will allow writers to determine whether their files have been restored to alternate locations through the IVssComponent::GetAlternateLocationMapping.
• Requesters may find it desirable to restore files to completely new locations. This is acceptable, but the requester must indicate this to the writer by using the IVssBackupComponents::AddNewTarget method.