Edit

Share via

Writer Metadata Document Contents

  • Article

The Writer Metadata Document contains three sets of data: writer identification and classification information, writer-level specifications, and component data.

Writer Identification Information

The writer identification and classification information includes the following:

With the exception of the writer instance, which is unique and is generated by the system when a CVssWriter object is initialized, all these values are set by a writer when it calls CVssWriter::Initialize and are available to a requester by calling IVssExamineWriterMetadata::GetIdentity.

Because the writer instance is uniquely generated, a stored writer instance retrieved from a stored Writer Metadata Document is not likely to be useful.

By checking VSS_USAGE_TYPE, an application can determine if a writer is managing general application data, or if the files it works with are part of the system's boot state or are used by a system service. Backup and restore applications need to respect usage types to help maintain system stability.

The VSS_SOURCE_TYPE flag indicates what type of application the writer managing the data to be backed up performs during normal operation.

Currently, the distinction is limited to specifying whether the writer produces files as part of transactional or nontransactional database operations, or if the files are the result of a more general type of activity. This list may grow over time. This information can be useful in determining the ordinary level of activity expected in the files of a writer.

Writer-Level Specification

Writer-level specifications contain information that is writer wide in its scope, applying to all data independent of which one component manages it.

A writer must always specify restore methods.

It may optionally specify the following:

The include and exclude file lists contain file information beyond that in the components, and their specification supersedes component specification.

Restore Method Specification

The restore method is set in the Writer Metadata Document by IVssCreateWriterMetadata::SetRestoreMethod and retrieved by a requester with IVssExamineWriterMetadata::GetRestoreMethod.

In setting a restore method, a writer indicates the preferred manner of file restoration, also known as the original restore target, for all files managed by a writer. For instance, the restore method specifies if all files managed by a writer should be allowed to overwrite files currently on disk. (See VSS Restore Configurations and VSS_RESTOREMETHOD_ENUM for more information.)

Exclude File List Specification

The exclude list allows fine-tuning of wildcard specifications in components by explicitly preventing certain files from being included in a backup set.

For instance, a component might have a file set containing a file specification of c:\Database\*.*. While this is a convenient definition, there may occasionally be temporary files generated (perhaps of the form *.tmp), and the writer always wants to prevent their backup.

In this case, a writer would add *.tmp to its exclude list using IVssCreateWriterMetadata::AddExcludeFiles. This specification could be recursive.

A requester would query this information by using IVssExamineWriterMetadata::GetExcludeFile.

The exclude file list takes precedence over component files lists.

Thus, the list of files specified for backup in a Writer Metadata Document would consist of all the files specified in the explicitly included components and the implicitly included components, less all excluded files.

Alternate Location Mappings Specification

Alternate location mappings are initially set during the creation of a Writer Metadata Document and indicate a location on disk to which files can be restored if restoration of a file to the original location is not possible.

The information is added as a null-terminated wide character string with IVssCreateWriterMetadata::AddAlternateLocationMapping and retrieved as an IVssWMFiledesc object by IVssExamineWriterMetadata::GetAlternateLocationMapping.

Despite the fact that alternate location mappings are specified and examined using the writer-level interfaces (IVssCreateWriterMetadata and IVssExamineWriterMetadata), they are specified in terms of file sets. The file set used in specifying an alternate location mapping (path, file specification, and recursion flag) must match one of the file sets already added to one of the writer's components (see Adding Files to Components).

For more information, see Non-Default Backup and Restore Locations.

Component-Level Information

Components are collections of files that form a logical unit for purposes of backup and restore. All files in a component (except those explicitly excluded) must be backed up and restored as a unit.

Writers add components using IVssCreateWriterMetadata::AddComponent, specifying the following component information:

  • Type
  • Name
  • Logical path (if any)
  • Supported feature
  • Selectability
  • Metadata to be used by the writer during restore
  • Display information
  • Notification information

Selectability for backup and selectability for restore are completely independent of each other, and a writer uses them in conjunction with logical paths to indicate relationships between the various components it manages. Writers can indicate which components are required for explicitly included (those that may be explicitly included at the discretion of a requester), and those that can only be implicitly included. (See Working with Selectability and Logical Paths.)

Files are added to a given component using either IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles. (See Adding Files To Components.)

When adding files to a component during backup, a writer must specify a file set (a path, file specification, and recursion flag) that defines the files to be backed up.

Writers can also specify an alternate path for backup, which should not be confused with alternate location mappings mentioned previously. This alternate path indicates a non-default location from which files are to be copied when a volume is backed up.

Information about a given component in the Writer Metadata Document can be obtained through an IVssWMComponent interface returned by IVssExamineWriterMetadata::GetComponent.

The files and paths are returned in IVssWMComponent as IVssWMFiledesc objects.

A writer's component information is discussed in detail in Definition of Components by Writers.