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:

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:

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

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**](/windows/desktop/api/VsWriter/nf-vswriter-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