Overview of Backup Initialization
This stage of the backup initializes both the writer and the requester, filling in their internal data structures, specifying the backup and establishes writer/requester communication through the required call to IVssBackupComponents::GatherWriterMetadata. For more information, see Overview of Processing a Backup Under VSS.
The following table shows the sequence of actions and events that are required for backup initialization.
| Requester action | Event | Writer action |
|---|---|---|
| Creates an IVssBackupComponents interface and initializes it to manage a backup (see CreateVssBackupComponents, IVssBackupComponents::InitializeForBackup) and optionally enable or disable writers on the system. | None | None |
| Optionally set the context for shadow copy operations and optionally query the system about the providers and shadow copies it supports (see IVssBackupComponents::SetContext, IVssBackupComponents::Query). | None | None |
| The requester can provide additional information on handling backup and restore operations (see IVssBackupComponents::SetBackupState) | None | None |
| Initiates asynchronous contact with writers (see IVssBackupComponents::GatherWriterMetadata) | Identify | Creates a Writer Metadata Document (see Working with the Writer Metadata Document, CVssWriter::OnIdentify, IVssCreateWriterMetadata) |
Requester Actions during Backup Initialization
An IVssBackupComponents object can be used for only one backup. Therefore, a requester must proceed through to the end of the backup, including releasing the IVssBackupComponents interface. If the backup needs to terminate prematurely, the requester needs to call IVssBackupComponents::AbortBackup and then release the IVssBackupComponents object (see Aborting VSS Operations for more information). Do not attempt to resume the IVssBackupComponents interface.
Typically, a requester's Backup Components Document is initialized as empty. A stored Backup Components Document can be loaded when IVssBackupComponents::InitializeForBackup is called, typically in support of transportable shadow copied volumes. In this case, the writer-requester communication will be somewhat different than what is described below. (See Importing Transportable Shadow Copied Volumes for more information.)
To add volumes to the shadow copy set, a requester must first set the context for the shadow copy operation by calling IVssBackupComponents::SetContext. If this method is not called, the default context for shadow copies, VSS_CTX_BACKUP, is used. For information about setting the shadow copy context, see Shadow Copy Context Configurations.
To begin the completion of its setup prior to backup, a requester must call IVssBackupComponents::SetBackupState. By doing this, a requester indicates to the writers:
- The type of backup (as defined in VSS_BACKUP_TYPE)
- Whether the backup includes a bootable system state
- Whether the requester supports the selection of individual components or backs up entire volumes.
All requesters participating in backup and restore operations must always call IVssBackupComponents::GatherWriterMetadata. This method initiates writer-requester communication by generating a VSS Identify event, in response to which a writer creates its metadata document.
Prior to calling IVssBackupComponents::GatherWriterMetadata, a requester has an opportunity to explicitly enable or disable certain specific writers and writer classes using IVssBackupComponents::EnableWriterClasses, IVssBackupComponents::DisableWriterInstances, and IVssBackupComponents::DisableWriterClasses (by default, all classes are enabled). After IVssBackupComponents::GatherWriterMetadata is called, these calls have no effect.
Because there is no way to obtain a list of writers on the system prior to calling IVssBackupComponents::GatherWriterMetadata, requesters may consider creating and then deleting a second instance of IVssBackupComponents to obtain the list.
It is not necessary to call IVssBackupComponents::GatherWriterStatus following the completion of IVssBackupComponents::GatherWriterMetadata. Writers that fail to process the Identify event generated by the calls will not be part of the list of writers providing metadata found by IVssBackupComponents::GetWriterMetadataCount and IVssBackupComponents::GetWriterMetadata (see Determining Writer Status).
Writer Actions during Backup Initialization
In response to the Identify event, VSS calls each writer's virtual handler method, CVssWriter::OnIdentify. A writer creates its Writer Metadata Document by overriding the default implementation of CVssWriter::OnIdentify and using the IVssCreateWriterMetadata interface.
Note that applications other than the current requester (for instance, system applications) can generate Identify events that must be handled by the writer. In addition, there is no way for a writer to determine from within CVssWriter::OnIdentify which application has generated the Identify event.
This being the case, given that a writer may receive several Identify events while processing a backup operation, a writer should never set state information in the CVssWriter::OnIdentify handler.
Instead, CVssWriter::OnIdentify should perform a consistent algorithm to create the writer's Writer Metadata Document, particularly because after a writer creates the document, neither the requester nor the writer can modify it. From this point forward, it is a read-only document.
This means that the number and type of components associated with a writer, which files are part of each component, and the explicit exclusion of files from backup or restore operations cannot be changed after a writer returns from processing the Identify event.
All writers participating with VSS are required to do the following:
- Indicate a restore method for all components managed by the writer using IVssCreateWriterMetadata::SetRestoreMethod.
- Add at least one component using IVssCreateWriterMetadata::AddComponent (see Definition of Components by Writers for more information on component specification).
A writer indicates the files to participate in a backup or restore operation by adding file sets—a combination of a path, file specification, and a recursion flag—to a given component using IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles, depending on type (See Adding Files to Components.)
A writer may also have one or more empty components, components to which no files have been added. These are very useful in organizing the writer's components. (See Logical Pathing of Components.)
A writer uses IVssCreateWriterMetadata::AddExcludeFiles to explicitly prevent files from being included in the backup. This explicit exclusion is useful because wildcard characters can be used to specify files for inclusion (see Exclude File List Specification). Note that the exclude file list takes precedence over component files lists.
IVssCreateWriterMetadata::AddAlternateLocationMapping is used to create alternate location mappings for specified file sets that have been added to one of the writer's components. These mappings are used during file restore when restoring to a file's original location is not possible or desirable. (See Overview of Actual File Restoration and Non-Default Backup and Restore Locations.)
Because the backup file set is specified in the Writer Metadata Document, it cannot later be modified. Therefore, a writer should be coded so that the file set's definition will include all files needed in the backup, either by name or through wildcard characters. Conceivably, this may include some files that might be created after the Identify event.