Backup Components Document Contents

The Backup Components Document is maintained by instances of the IVssBackupComponents interface. This interface also contains numerous methods for controlling backup operations, manipulating shadow copies, and querying the system state. However, not all of the document's information is directly accessible through this interface.

The Backup Components Document consists of several sets of data:

• Information about which components were explicitly included in a backup or restore operation
• A representation of the stored component and writer information
• State information about the backup/recover operation

While the component information is available to both the requester and the writer, only the writer has access to the state information.

Component Inclusion Information

The Backup Components Document contains a list of those components explicitly included in backup and restore by the requester. The list contains the following:

• Explicitly included selectable components.

  The inclusion of these files in backup operations is indicated by IVssBackupComponents::AddComponent and in restore operations by IVssBackupComponents::SetSelectedForRestore.

• Nonselectable for backup subcomponents without a selectable for backup component ancestor.

  All of these components must be included if any components of the writer are to be included in the operation. The inclusion of these files in backup operations is indicated by IVssBackupComponents::AddComponent and in restore operations by IVssBackupComponents::SetSelectedForRestore.

• Components implicitly added to the backup (subcomponents) that are selectable for restore and are explicitly added to the restore.

  These components may be either selectable or nonselectable, but have a selectable ancestor that was used to implicitly select them for backup. They are added to the Backup Components Document by IVssBackupComponents::AddRestoreSubcomponent.

The identities of components implicitly included in the restore are not stored in the Backup Components Document.

VSS has access to information about component inclusion: writers with no components explicitly included in a restore or backup receive no VSS events following the generation of the PrepareForBackup or PreRestore events.

Writers cannot directly query this information. This is not a significant limitation because by design, individual VSS writers should not require detailed information about the status of other writers on the system and, as noted above, those with no included components will not have to participate in the VSS operation.

A requester can determine which components have been explicitly included in an operation.

The IVssBackupComponents::GetWriterComponentsCount method returns the number of writers with component information stored in the Backup Components Document (and not the number of components in the document).

The requester indexes through the stored writer information using IVssBackupComponents::GetWriterComponents, which returns instances of the IVssWriterComponentsExt interface. The IVssWriterComponentsExt interface allows the requester to obtain the writer class and writer instance of participating writers, as well as to access information about those of its components stored in the Backup Components Document.

Information on Included Components

The Backup Components Document's representation of the component data (which does not include path and file specification information), which is accessed through instances of the IVssComponent interface.

Requesters and writers obtain access to instances of the IVssComponent interface in different ways.

A requester examines component data on a writer by writer basis by using instances of the IVssWriterComponentsExt interface returned by IVssBackupComponents::GetWriterComponents.

In addition to the writer identification information, the IVssWriterComponentsExt interface provides an array of instances of the IVssComponent interface—one for each of the selected writers included components.

As noted in Backup Components Document Life Cycle, the writers can gain access to the same information through the IVssWriterComponents interface when handling the PrepareForBackup, PrepareForSnapshot, PostSnapshot, BackupComplete, PreRestore, or PostRestore event.

IVssComponent allows both writer and requesters to get the following information:

• A component's name, type, and logical path (GetComponentName, GetComponentType, GetLogicalPath)
• How a component should be restored as indicated by the restore target (IVssComponent::GetRestoreTarget)
• If an alternate location was used in restoring a file (GetAlternateLocationMapping, GetAlternateLocationMappingCount)
• New target information, if any (GetNewTarget, GetNewTargetCount)
• Pre-and post-restore error messages (GetPreRestoreFailureMsg, GetPostRestoreFailureMsg)
• If a selectable for backup component defining a component set has been selected for restore (IsSelectedForRestore)
• Whether a backup or restore succeeded (GetBackupSucceeded, GetFileRestoreStatus)
• Any writer-specific backup or restore options that may have been set by IVssBackupComponents::SetBackupOptions or IVssBackupComponents::SetRestoreOptions (GetBackupOptions, GetRestoreOptions)
• Any writer-specific metadata backup or restore metadata (GetBackupMetadata), GetRestoreMetadata)
• Time-stamp information (GetBackupStamp, GetPreviousBackupStamp)
• Information about backup subcomponents explicitly included in a restore (GetRestoreSubcomponent, GetRestoreSubcomponentCount)

Unlike requesters, writers can change certain information in the Backup Components Document via the IVssComponent interface:

• How a component should be restored as indicated by the restore target (IVssComponent::SetRestoreTarget)
• Writer-specific backup and restore metadata (IVssComponent::SetBackupMetadata, IVssComponent::SetRestoreMetadata)
• Time-stamp information (SetBackupStamp)
• Pre- and post-restore error messages (SetPreRestoreFailureMsg, SetPostRestoreFailureMsg)

Requester State Information

Requesters insert information about the state of a backup or restore operation into the Backup Components Document using the IVssBackupComponents interface. Writer applications are able to query for this information through the CVssWriter class.

State information stored in the Backup Components Document includes the following:

General Information about the Backup

• The overall backup type (incremental, differential, or full)

Set by requesters using IVssBackupComponents::SetBackupState

Retrieved by writers using CVssWriter::GetBackupType

- Whether component operations are supported

Set by requesters using IVssBackupComponents::SetBackupState

Retrieved by writers using CVssWriter::AreComponentsSelected

- Whether the bootable system state is backed up

Set by requesters using IVssBackupComponents::SetBackupState

Retrieved by writers using CVssWriter::IsBootableStateBackedUp

- Whether partial file operations are supported

Set by requesters using IVssBackupComponents::SetBackupState

Retrieved by writers using CVssWriter::IsPartialFileSupportEnabled

General Information about the Restore

• The overall restore type (whether restore is by copy or import)

Set by requesters using IVssBackupComponents::SetRestoreState

Retrieved by writers using CVssWriter::GetRestoreType

Information about Supporting Files

• The location of ranges files used by a specific component in partial file operations

Set by requesters using IVssBackupComponents::SetRangesFilePath

Retrieved by writers (or requesters) using IVssComponent::GetPartialFile

Status of Information

• Indicate whether one of a given writer's components was successfully backed up

Set by requesters using IVssBackupComponents::SetBackupSucceeded

Retrieved by writers and requesters using IVssComponent::GetBackupSucceeded

- Indicate whether one of a given writer's components was successfully restored

Set by requesters using IVssBackupComponents::SetFileRestoreStatus

Retrieved by writers and requester using IVssComponent::GetFileRestoreStatus

Writer-Settable Information

• Additional backup specification for one of a given writer's components

Set by writers using IVssComponent::SetBackupMetadata

Retrieved by writers and requesters using IVssComponent::GetBackupMetadata

- Additional restore specification for one of a given writer's components

Set by writers using IVssComponent::SetRestoreMetadata

Retrieved by writers and requesters using IVssComponent::GetRestoreMetadata

- A backup stamp that indicates, in a writer's own specific format, the time of the current backup of one of its component's backups

Set by writers using IVssComponent::SetBackupStamp

Retrieved by writers and requesters using IVssComponent::GetBackupStamp

- A backup stamp that indicates, in a writer's own specific format, the time of the last backup of one of its components' backups using a backup stamp initially set by IVssComponent::SetBackupStamp

Stored and set by requesters for a specific component using IVssBackupComponents::SetPreviousBackupStamp

Retrieved by writers and requesters using IVssComponent::GetPreviousBackupStamp

- Error messages for failure before and after restore operations

Set by writers using IVssComponent::SetPreRestoreFailureMsg or IVssComponent::SetPostRestoreFailureMsg

Retrieved by writers and requesters using IVssComponent::GetPreRestoreFailureMsg or IVssComponent::GetPostRestoreFailureMsg