using System.Collections.Generic;
namespace Vanara.PInvoke.VssApi;
///
///
/// The VSS_ALTERNATE_WRITER_STATE enumeration is used to indicate whether a given writer has an associated alternate writer. The
/// existence of an alternate writer is set during writer initialization by CVssWriter::Initialize.
///
/// Currently, the only supported value for a method taking a VSS_ALTERNATE_WRITER_STATE argument is VSS_AWS_NO_ALTERNATE_WRITER.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_alternate_writer_state typedef enum
// VSS_ALTERNATE_WRITER_STATE { VSS_AWS_UNDEFINED, VSS_AWS_NO_ALTERNATE_WRITER, VSS_AWS_ALTERNATE_WRITER_EXISTS,
// VSS_AWS_THIS_IS_ALTERNATE_WRITER } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_ALTERNATE_WRITER_STATE")]
public enum VSS_ALTERNATE_WRITER_STATE
{
///
/// No information is available as to the existence of an alternate writer. This value indicates an application
/// error. This enumeration value is reserved for future use.
///
VSS_AWS_UNDEFINED = 0,
/// A given writer does not have an alternate writer.
VSS_AWS_NO_ALTERNATE_WRITER,
///
/// An alternate writer exists. This alternate writer runs when the writer is not available. This enumeration
/// value is reserved for future use.
///
VSS_AWS_ALTERNATE_WRITER_EXISTS,
/// The writer in question is an alternate writer. This enumeration value is reserved for future use.
VSS_AWS_THIS_IS_ALTERNATE_WRITER,
}
///
/// The VSS_COMPONENT_FLAGS enumeration is used by writers to indicate support for auto-recovery. These values are used in the
/// dwComponentFlags member of the VSS_COMPONENTINFO structure and the dwComponentFlags parameter of the
/// IVssCreateWriterMetadata::AddComponent method.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_component_flags typedef enum VSS_COMPONENT_FLAGS {
// VSS_CF_BACKUP_RECOVERY, VSS_CF_APP_ROLLBACK_RECOVERY, VSS_CF_NOT_SYSTEM_STATE } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_COMPONENT_FLAGS")]
[Flags]
public enum VSS_COMPONENT_FLAGS
{
///
/// The writer will need write access to this component after the shadow copy has been created.
/// This flag can be used together with the
/// VSS_VOLSNAP_ATTR_TRANSPORTABLE
/// value of the
/// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES
/// enumeration if the VSS hardware provider supports LUN masking.
/// Windows Vista and Windows Server 2003 with SP1:
/// This flag is incompatible with
/// VSS_VOLSNAP_ATTR_TRANSPORTABLE
/// .
/// This flag is not supported for express writers.
///
VSS_CF_BACKUP_RECOVERY = 0x01,
///
/// If this is a rollback shadow copy
/// (see the
/// VSS_VOLSNAP_ATTR_ROLLBACK_RECOVERY
/// value of the
/// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES
/// enumeration), the writer for this
/// component will need write access to this component after the shadow copy has been created.
/// This flag can be used together with the
/// VSS_VOLSNAP_ATTR_TRANSPORTABLE
/// value of the
/// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES
/// enumeration if the VSS hardware provider supports LUN masking.
/// Windows Vista and Windows Server 2003 with SP1:
/// This flag is incompatible with
/// VSS_VOLSNAP_ATTR_TRANSPORTABLE
/// .
/// This flag is not supported for express writers.
///
VSS_CF_APP_ROLLBACK_RECOVERY = 0x02,
///
/// This component is not part of system state.
/// Windows Server 2003 with SP1:
/// This value is not supported until Windows Vista.
///
VSS_CF_NOT_SYSTEM_STATE = 0x04,
}
///
/// The VSS_COMPONENT_TYPE enumeration is used by both the requester and the writer to specify the type of component being used
/// with a shadow copy backup operation.
///
///
/// A writer sets a component's type when it adds the component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent.
///
/// Writers and requesters can find the type information of components selected for inclusion in a Backup Components Document through
/// calls to IVssComponent::GetComponentType to return a component type directly.
///
/// A requester can obtain the type of any component in a given writer's Writer Metadata Document by doing the following:
///
/// -
/// Using IVssExamineWriterMetadata::GetComponent to obtain a IVssWMComponent interface
///
/// -
/// Using IVssWMComponent::GetComponentInfo to return a VSS_COMPONENTINFO structure
///
/// -
/// Examining the Type member of the VSS_COMPONENTINFO object
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_component_type typedef enum VSS_COMPONENT_TYPE {
// VSS_CT_UNDEFINED, VSS_CT_DATABASE, VSS_CT_FILEGROUP } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_COMPONENT_TYPE")]
public enum VSS_COMPONENT_TYPE
{
///
/// Undefined component type.
/// This value indicates an application error.
///
VSS_CT_UNDEFINED = 0,
/// Database component.
VSS_CT_DATABASE,
/// File group component. This is any component other than a database.
VSS_CT_FILEGROUP,
}
///
/// The VSS_FILE_RESTORE_STATUS enumeration defines the set of statuses of a file restore operation performed on the files
/// managed by a selected component or component set (see Working with Selectability and Logical Paths for information on selecting components).
///
///
///
/// If any files managed by a component or, if it defines a component set, any of its subcomponents cannot be restored, the value of
/// VSS_FILE_RESTORE_STATUS must indicate an error.
///
/// Both the values VSS_RS_FAILED and VSS_RS_NONE indicate that a restore operation did not complete successfully:
///
/// -
///
/// VSS_RS_NONE indicates a restore failed gracefully: no files from the component or its subcomponents were restored to disk.
///
///
/// -
/// VSS_RS_FAIL indicates a restore failed gracelessly, leaving some files restored to disk and some files unrestored.
///
///
///
/// Requesters must set a restore status (using IVssBackupComponents::SetFileRestoreStatus) for every component (and its component set,
/// if it defines one) explicitly added for restore to the Backup Components Document (using either
/// IVssBackupComponents::SetSelectedForRestore or IVssBackupComponents::AddRestoreSubcomponent).
///
///
/// Writers and requesters can query the status of the restoration of a component or a component set defined by a selectable component
/// with calls to IVssComponent::GetFileRestoreStatus. If this method is called for a component that was not selected, the value
/// returned is undefined.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_file_restore_status typedef enum VSS_FILE_RESTORE_STATUS
// { VSS_RS_UNDEFINED, VSS_RS_NONE, VSS_RS_ALL, VSS_RS_FAILED } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_FILE_RESTORE_STATUS")]
public enum VSS_FILE_RESTORE_STATUS
{
///
/// The restore state is undefined.
/// This value indicates an error, or indicates that a restore operation has not yet started.
/// This value is not supported for components that are owned by express writers.
///
VSS_RS_UNDEFINED = 0,
///
/// No files were restored.
/// This value indicates an error in restoration that did not leave any restored files on disk.
///
VSS_RS_NONE,
///
/// All files were restored. This value indicates success and should be set for each component that was
/// restored successfully.
///
VSS_RS_ALL,
///
/// The restore process failed.
/// This value indicates an error in restoration that did leave some restored files on disk. This means the
/// components on disk are now corrupt.
///
VSS_RS_FAILED,
}
///
///
/// The VSS_RESTORE_TARGET enumeration is used by a writer at restore time to indicate how all the files included in a selected
/// component, and all the files in any component set it defines, are to be restored. (See Working with Selectability and Logical Paths
/// for information on selecting components.)
///
/// Setting a restore target modifies or overrides the restore method set during backup (see VSS_RESTOREMETHOD_ENUM).
///
///
/// A target of VSS_RT_UNDEFINED indicates an error state.
///
/// At backup time, writers set the default restore behavior by indicating a restore method (VSS_RESTOREMETHOD_ENUM) set with IVssCreateWriterMetadata::SetRestoreMethod.
///
///
/// If a writer does not explicitly set the restore target of a component and any component set it defines, by default it is set to VSS_RT_ORIGINAL.
///
///
/// At restore time, a VSS_RESTORE_TARGET value other than VSS_RT_ORIGINAL overrides the value of the originally specified
/// restore method specified by VSS_RESTOREMETHOD_ENUM and set by IVssCreateWriterMetadata::SetRestoreMethod.
///
///
/// Only writers (using IVssComponent::SetRestoreTarget) can set a restore target ( VSS_RESTORE_TARGET) and change how files are
/// restored overriding the restore method).
///
/// Requesters and writers can access the current restore target through IVssComponent::GetRestoreTarget.
///
/// A restore target of VSS_RT_ORIGINAL does not mean that files should be restored to their original location, but that the
/// originally specified restore method (VSS_RESTOREMETHOD_ENUM) must be respected. For instance, if a writer set a restore method of
/// VSS_RME_RESTORE_TO_ALTERNATE_LOCATION for a selected component and the restore target is VSS_RT_ORIGINAL, files should
/// be restored to the alternate location defined by the writer.
///
///
/// (In this example, if a writer has failed to define alternate location mappings, then it is a writer error, and the requester should
/// report it.)
///
///
/// A restore target of VSS_RT_ALTERNATE without an alternate location mapping defined constitutes a writer error, and the
/// requester should report it as such.
///
/// See Non-Default Backup And Restore Locations for more information.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_restore_target typedef enum VSS_RESTORE_TARGET {
// VSS_RT_UNDEFINED, VSS_RT_ORIGINAL, VSS_RT_ALTERNATE, VSS_RT_DIRECTED, VSS_RT_ORIGINAL_LOCATION } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_RESTORE_TARGET")]
public enum VSS_RESTORE_TARGET
{
///
/// No target is defined.
/// This value indicates an error on the part of the writer.
/// This value is not supported for express writers.
///
VSS_RT_UNDEFINED = 0,
///
/// This is the default restore target.
/// This value indicates that the restoration of the files included in a selected component (or the component set
/// defined by that component) should proceed according to the original restore method specified at backup time by
/// a
/// VSS_RESTOREMETHOD_ENUM
/// value.
///
VSS_RT_ORIGINAL,
///
/// The files are restored to a location determined from an existing alternate location mapping.
/// The restore target should be set to
/// VSS_RT_ALTERNATE
/// only when alternate location
/// mappings have been set for all the files managed by a selected component or component set.
/// This value is not supported for express writers.
///
VSS_RT_ALTERNATE,
///
/// Use directed targeting by the writer at restore time to restore a file.
/// Directed targeting allows a writer to control, on a file-by-file basis, how a file is
/// restored—indicating how much of a file is to be restored and into which files the
/// backed-up file is to be restored.
/// This value is not supported for express writers.
///
VSS_RT_DIRECTED,
///
/// The files are restored to the location at which they were at backup time, even if the original
/// restore method that was specified at backup time was
/// VSS_RME_RESTORE_TO_ALTERNATE_LOCATION
/// .
/// Windows Server 2003 and Windows XP:
/// This value is not supported.
/// This value is not supported for express writers.
///
VSS_RT_ORIGINAL_LOCATION,
}
///
///
/// The VSS_RESTOREMETHOD_ENUM enumeration is used by a writer at backup time to specify through its Writer Metadata Document the
/// default file restore method to be used with all the files in all the components it manages.
///
///
/// The restore method is writer-wide and is also referred to as the original restore target and indicated by a VSS_RESTORE_TARGET value
/// of VSS_RT_ORIGINAL.
///
///
///
///
/// A writer sets the restore method in the Writer Metadata Document by calling IVssCreateWriterMetadata::SetRestoreMethod during backup
/// to specify its desired restore method in its metadata.
///
///
/// A requester retrieves a writer's requested restore method by calling IVssExamineWriterMetadata::GetRestoreMethod and acts accordingly.
///
/// The restore method applies to all files in all components of a given writer.
///
/// The restore method may be overridden on a component-by-component basis at restore time if a writer sets a VSS_RESTORE_TARGET value
/// other than VSS_RT_ORIGINAL with IVssComponent::SetRestoreTarget.
///
///
/// A restore method of VSS_RME_RESTORE_TO_ALTERNATE_LOCATION without an alternate location mapping defined constitutes a writer
/// error, and the requester should report it as such.
///
///
/// When a restore method requires a check on the status of files currently on disk ( VSS_RME_RESTORE_IF_NOT_THERE,
/// VSS_RME_RESTORE_IF_CAN_REPLACE, or VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE), ideally, you should use file I/O
/// operations to verify that an entire component can be restored before actually proceeding with the restore.
///
/// The safest way to do this would be to open exclusively (no-sharing) all the target files with CreateFile prior to the restore.
/// In the case of VSS_RME_RESTORE_IF_NOT_THERE, a creation disposition flag of CREATE_NEW should also be set.
///
/// If the open operations succeed, the restore can proceed and should use the handles returned by CreateFile to actually write restored
/// data to disk.
///
///
/// If not, an error can be returned—depending on the method—or alternate location mapping checked and (if it is available) used, or the
/// components files staged for restore at the next reboot.
///
/// This may be a problem for very large components (some of which may have thousands of files), due to system overhead.
/// In this case, an available though less reliable option is to do the following:
///
/// -
/// Copy all files currently on disk and to be restored to a temporary cache.
///
/// -
///
/// Attempt to replace the files currently on disk with the backed-up files (which could be either on disk in a second temporary area,
/// or on a backup medium).
///
///
/// -
///
/// If any files fail to restore, then terminate the restore operation and copy the original files back from their temporary location
/// and proceed with alternate location mapping or restore on reboot operations.
///
///
///
/// For more information on backup and restore file locations under VSS, see Non-Default Backup And Restore Locations.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_restoremethod_enum typedef enum VSS_RESTOREMETHOD_ENUM {
// VSS_RME_UNDEFINED, VSS_RME_RESTORE_IF_NOT_THERE, VSS_RME_RESTORE_IF_CAN_REPLACE, VSS_RME_STOP_RESTORE_START,
// VSS_RME_RESTORE_TO_ALTERNATE_LOCATION, VSS_RME_RESTORE_AT_REBOOT, VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE, VSS_RME_CUSTOM,
// VSS_RME_RESTORE_STOP_START } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_RESTOREMETHOD_ENUM")]
public enum VSS_RESTOREMETHOD_ENUM
{
///
/// No restore method is defined.
/// This indicates an error on the part of the writer.
/// This value is not supported for express writers.
///
VSS_RME_UNDEFINED = 0,
///
/// The requester should restore the files of a selected component or component set only if there are no versions of
/// those files currently on the disk.
/// Unless alternate location mappings are defined for file restoration, if a version of any file managed by a
/// selected component or component set is currently on the disk, none of the files managed by the selected
/// component or component set should be restored.
/// If a file's alternate location mapping is defined, and a version of the files is present on disk at the
/// original location, files should be written to the alternate location only if no version of the file exists at
/// the alternate location.
///
VSS_RME_RESTORE_IF_NOT_THERE,
///
///
/// The requester should restore files of a selected component or component set only if the files currently on the disk can be overwritten.
///
/// Unless alternate location mappings are defined for file restoration, if there is a version of any file that
/// cannot be overwritten of the selected component or component set on the disk, none of the files managed by the
/// component or component set should be restored.
/// If a file's alternate location mapping is defined, files should be written to the alternate location.
///
VSS_RME_RESTORE_IF_CAN_REPLACE,
///
/// The requester should perform the restore operation as follows:
///
/// -
/// Send the PreRestore event and wait for all writers to process it.
///
/// -
/// Stop the service.
///
/// -
/// Restore the files to their original locations.
///
/// -
/// Restart the service.
///
/// -
/// Send the PostRestore event and wait for all writers to process it.
///
///
/// The service to be stopped is specified the writer beforehand when it calls the
/// IVssCreateWriterMetadata::SetRestoreMethod
/// method. The requester can obtain the name of the service by calling the
/// IVssExamineWriterMetadata::GetRestoreMethod
/// method.
/// Note that if the writer is hosted in the service that is being stopped, that writer will not receive the
/// PostRestore
/// event, because the writer instance ID changes when the service is stopped and restarted.
///
VSS_RME_STOP_RESTORE_START,
///
/// The requester should restore the files of the selected component or component set to the location specified by the
/// alternate location mapping specified in the writer component metadata file. (See
/// IVssCreateWriterMetadata::AddAlternateLocationMapping
/// ,
/// IVssComponent::GetAlternateLocationMapping
/// ,
/// IVssExamineWriterMetadata::GetAlternateLocationMapping
/// ,
/// and
/// IVssWMFiledesc::GetAlternateLocation
/// .)
/// This value is not supported for express writers.
///
VSS_RME_RESTORE_TO_ALTERNATE_LOCATION,
///
/// The requester should restore the files of a selected component or component set after the computer is restarted.
/// The files to be restored should be copied to a temporary location, and the requester should use
/// MoveFileEx
/// with the
/// MOVEFILE_DELAY_UNTIL_REBOOT
/// flag to complete the restoration of these files to their
/// proper location after the computer is restarted.
///
VSS_RME_RESTORE_AT_REBOOT,
///
/// If possible, the requester should restore the files of the selected component or component set to their correct
/// location immediately.
/// If there are versions of any of the files managed by the selected component or component set on the disk that
/// cannot be overwritten, then all the files managed by the selected component or component set should be restored
/// after the computer is restarted.
/// In this case, files to be restored should be copied to a temporary location on disk, and the requester should
/// use
/// MoveFileEx
/// with the
/// MOVEFILE_DELAY_UNTIL_REBOOT
/// flag to complete the restoration of these files to their
/// proper location after the computer is restarted.
///
VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE,
///
/// The requester should use a custom restore method to restore the files that are managed by the selected
/// component or component set.
/// A custom restore may use file retrieval API functions or protocols that are private to a given writer
/// application. Such a restore need not use the information in the writer component metadata file. (See
/// Custom Backups and Restores
/// for more
/// information.)
/// This value is not supported for express writers.
///
VSS_RME_CUSTOM,
///
/// The requester should perform the restore operation as follows:
///
/// -
/// Send the PreRestore event and wait for all writers to process it.
///
/// -
/// Restore the files to their original locations.
///
/// -
/// Send the PostRestore event and wait for all writers to process it.
///
/// -
/// Stop the service.
///
/// -
/// Restart the service.
///
///
/// The service to be stopped is specified by the writer beforehand when it calls the
/// IVssCreateWriterMetadata::SetRestoreMethod
/// method. The requester can obtain the name of the service by calling the
/// IVssExamineWriterMetadata::GetRestoreMethod
/// method.
///
VSS_RME_RESTORE_STOP_START,
}
/// The VSS_SOURCE_TYPE enumeration specifies the type of data that a writer manages.
///
///
/// The source type of the data that a writer manages is specified when it initializes its cooperation with the shadow copy mechanism
/// through a call to CVssWriter::Initialize.
///
/// Information about the source type of the data that a writer manages can be retrieved through its metadata using IVssExamineWriterMetadata::GetIdentity.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_source_type typedef enum VSS_SOURCE_TYPE {
// VSS_ST_UNDEFINED, VSS_ST_TRANSACTEDDB, VSS_ST_NONTRANSACTEDDB, VSS_ST_OTHER } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_SOURCE_TYPE")]
public enum VSS_SOURCE_TYPE
{
///
/// The source of the data is not known.
/// This indicates a writer error, and the requester should report it.
///
VSS_ST_UNDEFINED = 0,
/// The source of the data is a database that supports transactions, such as Microsoft SQL Server.
VSS_ST_TRANSACTEDDB,
/// The source of the data is a database that does not support transactions.
VSS_ST_NONTRANSACTEDDB,
///
/// Unclassified source type—data will be in a file group.
/// This is the default source type.
///
VSS_ST_OTHER,
}
///
/// The VSS_SUBSCRIBE_MASK enumeration is used by a writer when subscribing to the VSS service. It indicates the events that the
/// writer is willing to receive.
///
///
/// A bit mask (or bitwise OR) of VSS_SUBSCRIBE_MASK values is used as an argument only to CVssWriter::Subscribe.
/// Currently, the only supported VSS_SUBSCRIBE_MASK bit mask is ( VSS_SM_BACKUP_EVENTS_FLAG | VSS_SM_RESTORE_EVENTS_FLAG).
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_subscribe_mask typedef enum VSS_SUBSCRIBE_MASK {
// VSS_SM_POST_SNAPSHOT_FLAG, VSS_SM_BACKUP_EVENTS_FLAG, VSS_SM_RESTORE_EVENTS_FLAG, VSS_SM_IO_THROTTLING_FLAG, VSS_SM_ALL_FLAGS } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_SUBSCRIBE_MASK")]
[Flags]
public enum VSS_SUBSCRIBE_MASK : uint
{
///
/// This enumeration value is reserved for future use.
/// Specifies that the writer expects to be notified after the shadow copy it is participating in has completed.
/// It will then call
/// CVssWriter::OnPostSnapshot
/// .
///
VSS_SM_POST_SNAPSHOT_FLAG = 0x01,
///
/// Currently,
/// VSS_SM_BACKUP_EVENTS_FLAG
/// can be used as an argument only when
/// combined through a bitwise OR with
/// VSS_SM_RESTORE_EVENTS_FLAG
/// .
/// Specifies that the writer can expect to receive the following events:
///
/// -
/// A PrepareForSnapshot event when the writer will call CVssWriter::OnPrepareSnapshot.
///
/// -
/// A PrepareForBackup event when the writer will call CVssWriter::OnPrepareBackup.
///
/// -
/// A Freeze event when the writer will call CVssWriter::OnFreeze.
///
/// -
/// A BackupComplete event when the writer will call CVssWriter::OnBackupComplete.
///
/// -
/// A Thaw event when the writer will call CVssWriter::OnThaw.
///
/// -
/// A PostSnapshot event when the writer will call CVssWriter::OnPostSnapshot.
///
///
///
VSS_SM_BACKUP_EVENTS_FLAG = 0x02,
///
/// Currently,
/// VSS_SM_RESTORE_EVENTS_FLAG
/// can be used as an argument only when
/// combined through a bitwise OR with
/// VSS_SM_BACKUP_EVENTS_FLAG
/// .
/// Specifies that the writer can expect to receive the following events:
///
/// -
/// A PreRestore event when the writer will call CVssWriter::OnPreRestore.
///
/// -
/// A PostRestore event when the writer will call CVssWriter::OnPostRestore.
///
///
///
VSS_SM_RESTORE_EVENTS_FLAG = 0x04,
/// This enumeration value is reserved for future use.
VSS_SM_IO_THROTTLING_FLAG = 0x08,
///
/// This enumeration value is reserved for future use.
/// Specifies that the writer expects to be notified for all events.
///
VSS_SM_ALL_FLAGS = 0xFFFFFFFF,
}
///
/// The VSS_USAGE_TYPE enumeration specifies how the host system uses the data managed by a writer involved in a VSS operation.
///
///
///
/// The usage type of the data that a writer manages is specified when it initializes its cooperation with the shadow copy mechanism
/// through CVssWriter::Initialize.
///
/// Information about the usage type of the data that a writer manages can be retrieved through its metadata using IVssExamineWriterMetadata::GetIdentity.
///
/// Requester applications that are interested in backing up system state should look for writers with the
/// VSS_UT_BOOTABLESYSTEMSTATE or VSS_UT_SYSTEMSERVICE usage type.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_usage_type typedef enum VSS_USAGE_TYPE {
// VSS_UT_UNDEFINED, VSS_UT_BOOTABLESYSTEMSTATE, VSS_UT_SYSTEMSERVICE, VSS_UT_USERDATA, VSS_UT_OTHER } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_USAGE_TYPE")]
public enum VSS_USAGE_TYPE
{
///
/// The usage type is not known.
/// This indicates an error on the part of the writer.
///
VSS_UT_UNDEFINED = 0,
/// The data stored by the writer is part of the bootable system state.
VSS_UT_BOOTABLESYSTEMSTATE,
/// The writer either stores data used by a system service or is a system service itself.
VSS_UT_SYSTEMSERVICE,
/// The data is user data.
VSS_UT_USERDATA,
/// Unclassified data.
VSS_UT_OTHER,
}
///
/// The VSS_WRITERRESTORE_ENUM enumeration is used by a writer to indicate to a requester the conditions under which it will
/// handle events generated during a restore operation.
///
///
///
/// A writer passes a value of VSS_WRITERRESTORE_ENUM to IVssCreateWriterMetadata::SetRestoreMethod to indicate through its
/// metadata how it interacts with requesters during a restore operation.
///
/// A requester retrieves information about a writer's participation by calling IVssExamineWriterMetadata::GetRestoreMethod.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_writerrestore_enum typedef enum VSS_WRITERRESTORE_ENUM {
// VSS_WRE_UNDEFINED, VSS_WRE_NEVER, VSS_WRE_IF_REPLACE_FAILS, VSS_WRE_ALWAYS } ;
[PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_WRITERRESTORE_ENUM")]
public enum VSS_WRITERRESTORE_ENUM
{
///
/// It is not known whether the writer will perform special operations during the restore operation.
/// This state indicates a writer error.
///
VSS_WRE_UNDEFINED = 0,
/// The writer does not require restore events.
VSS_WRE_NEVER,
///
/// Indicates that the writer always expects to handle a
/// PreRestore
/// (
/// CvssWriter::OnPreRestore
/// ) event, but expects
/// to handle a
/// PostRestore
/// event
/// (
/// CvssWriter::OnPostRestore
/// ) only if a restore
/// fails when implementing either a
/// VSS_RME_RESTORE_IF_NOT_THERE
/// or
/// VSS_RME_RESTORE_IF_CAN_REPLACE
/// restore method
/// (
/// VSS_RESTOREMETHOD_ENUM
/// ).
///
VSS_WRE_IF_REPLACE_FAILS,
/// The writer always performs special operations during the restore operation.
VSS_WRE_ALWAYS,
}
/// Defines methods to manipulate a list that can be appended.
/// The type of the elements in the collection.
public interface IAppendOnlyList : IReadOnlyList
{
/// Adds an item to the list.
/// The object to add to the list.
void Add(T item);
}
///
///
/// The IVssComponent interface contains methods for examining and modifying information about components contained in a
/// requester's Backup Components Document.
///
///
/// IVssComponent objects can be obtained only for those components that have been explicitly added to the Backup Components
/// Document during a backup operation by the IVssBackupComponents::AddComponent method.
///
///
/// Information about components explicitly added during a restore operation using IVssBackupComponents::AddRestoreSubcomponent are not
/// available through the IVssComponent interface.
///
///
/// Some information common to both components and implicitly selected subcomponents available through IVssComponent objects
/// includes the following:
///
///
/// -
/// Backup time stamp
///
/// -
/// Pre-/post-restore Failure Messages
///
/// -
/// Restore metadata
///
/// -
/// Restore target
///
///
///
/// Some information in the IVssComponent object is on a per-file basis and can refer to files managed either by explicitly
/// selected components or by implicitly selected subcomponents:
///
///
/// -
/// Alternate location mappings
///
/// -
/// Partial files
///
/// -
/// Directed target
///
///
///
/// Other information is not included in the Backup Components Document and can be inferred using the IVssComponent object in
/// conjunction with the appropriate Writer Metadata Documents based on a writer's component hierarchy expressed in the logical paths
/// (see Working with Selectability and Logical Paths).
///
///
/// The interface can be used by either a writer or a requester, although certain methods are supported only for writers. In this way, a
/// writer can request changes in a backup or restore operation, such as adding a new target, or learn of requester actions, such as the
/// use of an alternate location.
///
/// The following methods return an IVssComponent interface:
///
/// -
/// IVssWriterComponents::GetComponent
///
/// -
/// IVssWriterComponentsExt::GetComponent
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscomponent
[PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssComponent")]
public interface IVssComponent
{
///
///
/// The GetAdditionalRestores method is used by a writer during incremental or differential restore operations to determine
/// whether a given component will require additional restore operations to completely retrieve it.
///
/// Either a writer or a requester can call this method.
///
///
/// The address of a caller-allocated variable that receives true if additional restores will occur for the current
/// component, or false otherwise.
///
///
///
/// The value returned by GetAdditionalRestores will be false, unless during a restore operation a requester calls IVssBackupComponents::SetAdditionalRestores.
///
///
/// GetAdditionalRestores should be used to check if it is necessary to use more than one backup set to completely restore a
/// component. A component might first be retrieved by restoring data from a full backup, and then updating that data from one or
/// more subsequent incremental or differential backups.
///
///
/// The GetAdditionalRestores method is typically used by writers that support an explicit recovery mechanism as part of
/// their PostRestore event handler (CVssWriter::OnPostRestore)—for instance, the Exchange Server, and database applications such as
/// SQL Server. For these applications, it is often not possible to perform additional differential, incremental, or log restores
/// after such a recovery is performed.
///
///
/// Therefore, if GetAdditionalRestores returns true for a component, such a writer should not execute its explicit
/// recovery mechanism and should expect that additional differential, incremental, or log restores will be done.
///
///
/// When SetAdditionalRestores returns false, then after the restore has finished, when handling the PostRestore event, the
/// writer can complete its recovery operation and be brought back online.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getadditionalrestores HRESULT
// GetAdditionalRestores( [out] bool *pbAdditionalRestores );
bool AdditionalRestores { get; }
///
/// The AlternateLocationMappings property is used to return a file set's alternate locations for file restoration. This can
/// be called by either a writer or a requester.
///
/// List of IVssWMFiledesc objects containing the mapping information.
///
///
/// The value returned by IVssComponent::GetAlternateLocationMapping should also not be confused with that returned by IVssExamineWriterMetadata::GetAlternateLocationMapping:
///
///
/// -
///
/// IVssExamineWriterMetadata::GetAlternateLocationMapping is the alternate location mapping to which a file may be restored if necessary.
///
///
/// -
/// IVssComponent::GetAlternateLocationMapping is the alternate location to which a file was in fact restored.
///
///
/// A file should always be restored to its alternate location mapping if either of the following is true:
///
/// -
/// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION.
///
/// -
/// Its restore target was set (at restore time) to VSS_RT_ALTERNATE.
///
///
/// In either case, having no alternate location mapping defined constitutes a writer error.
/// A file can be restored to an alternate location mapping if either of the following is true:
///
/// -
/// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk.
///
/// -
/// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced.
///
///
///
/// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which
/// is used only during a backup operation.
///
///
/// The mapping returned by GetAlternateLocationMapping refers to the alternate location mappings used in the course of
/// restoring files.
///
/// Alternate location mappings are added to an IVssComponent object by IVssBackupComponents::AddAlternativeLocationMapping.
/// For more information on backup and restore file locations under VSS, see Non-Default Backup And Restore Locations.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getalternatelocationmapping HRESULT
// GetAlternateLocationMapping( [in] UINT iMapping, [out] IVssWMFiledesc **ppFiledesc );
IReadOnlyList AlternateLocationMappings { get; }
/// Determines whether a requester has marked the restore of a component as authoritative for a replicated data store.
///
/// The address of a caller-allocated variable that receives true if the restore is authoritative, or false otherwise.
///
///
///
/// A writer indicates that it supports authoritative restore by setting the VSS_BS_AUTHORITATIVE_RESTORE flag in its backup
/// schema mask.
///
/// For more information, see Setting VSS Restore Options.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getauthoritativerestore HRESULT
// GetAuthoritativeRestore( [out] bool *pbAuth );
bool AuthoritativeRestore { get; }
///
///
/// The GetBackupMetadata method retrieves private, writer-specific backup metadata that might have been set during a
/// PrepareForBackup event by CVssWriter::OnPrepareBackup using IVssComponent::SetBackupMetadata.
///
/// Only a writer can call this method.
///
///
/// The address of a caller-allocated variable that receives a string containing the backup metadata that was added during an
/// OnPrepareBackup event.
///
///
/// This method can be called at any time depending on the logic of a given writer.
/// If no backup metadata has been set, GetBackupMetadata returns S_FALSE.
///
/// If the call to GetBackupMetadata is successful, the caller is responsible for freeing the string that is returned in the
/// pbstrMetadata parameter by calling the SysFreeString function.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getbackupmetadata HRESULT
// GetBackupMetadata( [out] BSTR *pbstrData );
string BackupMetadata { get; set; }
///
///
/// The GetBackupOptions method returns the backup options specified to the writer that manages the currently selected
/// component or component set by a requester using IVssBackupComponents::SetBackupOptions.
///
/// Either a writer or a requester can call this method.
///
///
/// The address of a caller-allocated variable that receives a string containing the backup options for the current writer.
///
///
/// If no backup options have been set, S_FALSE is returned.
///
/// If the call to GetBackupOptions is successful, the caller is responsible for freeing the string that is returned in the
/// pbstrBackupOptions parameter by calling the SysFreeString function.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getbackupoptions HRESULT GetBackupOptions(
// [out] BSTR *pbstrBackupOptions );
string BackupOptions { get; }
///
/// The GetBackupStamp method returns the backup stamp string stored by a writer for a given component.
/// Either a writer or a requester can call this method.
///
///
/// The address of a caller-allocated variable that receives a string containing the backup stamp indicating the time at which the
/// component was backed up.
///
///
/// If no backup time stamp has been set, GetBackupStamp returns S_FALSE.
///
/// If the call to GetBackupStamp is successful, the caller is responsible for freeing the string that is returned in the
/// pbstrBackupStamp parameter by calling the SysFreeString function.
///
/// The string returned refers to all files in the component and any nonselectable subcomponents it has.
///
/// The backup stamp retrieved by GetBackupStamp is generally set by a writer by a call to IVssComponent::SetBackupStamp from
/// within the PostSnapshot event handler, CVssWriter::OnPostSnapshot.
///
///
/// Requesters merely store the backup stamps in the Backup Components Document; they do not make direct use of the backup stamp,
/// know how to generate it, or understand its format.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getbackupstamp HRESULT GetBackupStamp(
// [out] BSTR *pbstrBackupStamp );
string BackupStamp { get; set; }
///
///
/// The GetBackupSucceeded method returns the status of a complete attempt at backing up all the files of a selected
/// component or component set as a VSS_FILE_RESTORE_STATUS enumeration. (See Working with Selectability and Logical Paths for
/// information on selecting components.)
///
/// Either a writer or a requester can call this method.
///
///
/// The address of a caller-allocated variable that receives true if the backup was successful, or false otherwise.
///
///
/// This method should not be called prior to a BackupComplete event, and is designed for use in an implementation of the event
/// handler CVssWriter::OnBackupComplete.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getbackupsucceeded HRESULT
// GetBackupSucceeded( [out] bool *pbSucceeded );
bool BackupSucceeded { get; }
///
/// The GetComponentName method returns the logical name of this component.
/// Either a writer or a requester can call this method.
///
/// Pointer to a string containing the logical name of the component.
/// The caller should free the memory held by the pwszName parameter by calling SysFreeString.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getcomponentname HRESULT GetComponentName(
// [out] BSTR *pbstrName );
string ComponentName { get; }
///
/// The GetComponentType method returns the type of this component in terms of the VSS_COMPONENT_TYPE enumeration.
/// Either a writer or a requester can call this method.
///
///
/// The address of a caller-allocated variable that receives a VSS_COMPONENT_TYPE enumeration value that specifies the type of the component.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getcomponenttype HRESULT GetComponentType(
// [out] VSS_COMPONENT_TYPE *pct );
VSS_COMPONENT_TYPE ComponentType { get; }
///
///
/// The GetDifferencedFile method returns information about a file set (a specified file or files) to participate in an
/// incremental or differential backup or restore as a differenced file—that is, backup and restores associated with it are to be
/// implemented as if entire files are copied to and from backup media (as opposed to using partial files).
///
/// This method can be called by a requester or a writer during backup or restore operations.
///
///
/// GetDifferencedFile can be called by a requester or a writer during backup or restore operations.
///
/// If the call to GetDifferencedFile is successful, the caller is responsible for freeing the string that is returned in the
/// pbstrPath and pbstrFilespec parameters by calling the SysFreeString function.
///
///
/// As writers can indicate differenced files with calls to IVssComponent::AddDifferencedFilesByLastModifyTime at any time prior to
/// the actual backing up of files, typically while handling a PostSnapshot event (CVssWriter::OnPostSnapshot), during backups
/// GetDifferencedFile is not usefully called prior to the return of IVssBackupComponents::DoSnapshotSet has successfully returned.
///
///
/// The time stamp returned by GetDifferencedFile applies to all files that match the returned path (pbstrPath) and file
/// specification (pbstrFilespec).
///
///
/// If the time-stamp value returned by GetDifferencedFile (pftLastModifyTime) is nonzero, a requester must respect this
/// value regardless of its own records and file system information and use it to determine whether the differenced file should be
/// included in a differential or incremental backup.
///
///
/// If the time stamp returned by GetDifferencedFile is zero, the requester can use file system information and its own
/// records to determine whether the differenced files should be included in a differential or incremental backup.
///
/// Differenced files can be either of the following:
///
/// -
///
/// Members of the current component or, if the component defines a component set, members of its subcomponents that were added to
/// the component using IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles
///
///
/// -
/// New files added to the component by IVssComponent::AddDifferencedFilesByLastModifyTime
///
///
///
/// When referring to a file set that is already part of the component, the combination of path, file specification, and recursion
/// flag (wszPath, wszFileSpec, and bRecursive, respectively) used when calling GetDifferencedFile should match that of a
/// file set already in the component, or one of its subcomponents (if the component defines a component set).
///
///
/// When GetDifferencedFile returns a differenced new file, that file's path (pbstrPath) should match or be beneath a path
/// already in the component, or one of its subcomponents (if the component defines a component set).
///
/// In addition, the files returned by GetDifferencedFile should not already be managed by component or writer.
/// If any of these criteria are violated, they constitute an error on the part of the writer and should be reported.
///
/// There is no method in the IVssComponent interface that allows for changing or adding an alternate location mapping for new files
/// returned by GetDifferencedFilesByLastModifyTime. If an alternate location mapping corresponds to the new file, then that
/// alternate location will be used.
///
///
IAppendOnlyList DifferencedFiles { get; }
///
///
/// The DirectedTargets property returns information stored by a writer, at backup time, to the Backup Components Document to
/// indicate that when a file is to be restored, it (the source file) should be remapped. The file may be restored to a new restore
/// target and/or ranges of its data restored to different locations with the restore target.
///
/// Either a writer or a requester can call this method.
///
///
///
/// A requester will use the directed target information stored in the Backup Components Document only if the restore target is VSS_RT_DIRECTED.
///
///
/// The syntax of the range listing (wszSourceRanges and wszDestinationRanges) is that of a comma-separated list of the form
/// offset1:length1, offset2:length2, where each offset and length is a 64-bit integer specifying a byte offset and length in
/// bytes, respectively. The offset and length can be expressed either as hexadecimal or decimal values.
///
///
/// Files whose directed targets are returned by GetDirectedTarget may be members of the files of the current component or
/// any subcomponent it defines.
///
///
/// Partial files may be added as directed targets, if the partial file ranges to be backed up match the directed target source
/// ranges (see IVssComponent::AddPartialFile). This will allow you to remap partial files.
///
///
/// The requester will need to check if the directed target source file was backed up as a partial file to correctly implement the
/// restore. If this is the case, the requester uses the directed target information in conjunction with the partial file
/// information (IVssComponent::GetPartialFile) to implement the remapping of the backed-up data during restore.
///
///
IAppendOnlyList DirectedTargets { get; }
///
///
/// The GetFileRestoreStatus method returns the status of a completed attempt to restore all the files of a selected
/// component or component set as a VSS_FILE_RESTORE_STATUS enumeration. (See Working with Selectability and Logical Paths for
/// information on selecting components.)
///
/// Either a writer or a requester can call this method.
///
///
/// The address of a caller-allocated variable that receives a VSS_FILE_RESTORE_STATUS enumeration value that specifies whether all
/// files were successfully restored.
///
///
/// This method should be called only following a PostRestore event.
///
/// The status returned is undefined if this method is applied to a component that has not been selected for restore by being added
/// to the Backup Components via IVssBackupComponents::AddComponent.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getfilerestorestatus HRESULT
// GetFileRestoreStatus( [out] VSS_FILE_RESTORE_STATUS *pStatus );
VSS_FILE_RESTORE_STATUS FileRestoreStatus { get; }
///
/// The IsSelectedForRestore method determines whether the current component has been selected to be restored.
/// Either a writer or a requester can call this method.
///
///
/// The address of a caller-allocated variable that receives true if the component has been selected to be restored, or
/// false otherwise.
///
///
/// IsSelectedForRestore is relevant only under component mode.
/// If the component defines a component set, IsSelectedForRestore refers both to the component and all of its subcomponents.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-isselectedforrestore HRESULT
// IsSelectedForRestore( [out] bool *pbSelectedForRestore );
bool IsSelectedForRestore { get; }
///
/// The GetLogicalPath method returns the logical path of this component.
/// Either a writer or a requester can call this method.
///
/// Pointer to a string containing the logical path of the component.
///
/// The caller should free the memory held by the pbstrPath parameter by calling SysFreeString.
/// Logical paths are not required of components. A component without a logical path will return S_FALSE.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getlogicalpath HRESULT GetLogicalPath(
// [out] BSTR *pbstrPath );
string LogicalPath { get; }
///
///
/// The NewTargets property returns the new file restoration locations. (See Working with Selectability and Logical Paths for
/// information on selecting components.)
///
/// Either a writer or a requester can call this method.
///
/// List of IVssWMFiledesc objects containing the new target restore locations information.
///
/// New targets returned by NewTargets may be those not only of files in the current component but to files in any of its
/// nonselectable subcomponents.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getnewtarget HRESULT GetNewTarget( [in]
// UINT iNewTarget, [out] IVssWMFiledesc **ppFiledesc );
IReadOnlyList NewTargets { get; }
/// The PartialFiles property returns information on the partial files associated with this component.
///
/// A range indicates a subsection of a given file that is to be backed up, independent of the rest of the file.
///
/// The syntax of the range listing (pbstrRanges) is that of a comma-separated list of the form offset1:length1,
/// offset2:length2, where each offset and length is a 64-bit integer specifying a byte offset and length in bytes,
/// respectively. The offset and length can be expressed either as hexadecimal or decimal values.
///
///
/// If pbstrRanges refers to a file containing all the offsets and lengths (a ranges file), pbstrRanges should contain the full path
/// to the file.
///
///
/// If wszRange refers to a file containing all the offsets and lengths (a ranges file), wszRange should contain the full path to
/// the file.
///
/// A ranges file must be a binary file with the following format:
///
/// -
/// A 64-bit integer indicating the number of distinct file ranges that need to be backed up.
///
/// -
///
/// Each range expressed as a pair of 64-bit integers: the offset into the file being backed up, in bytes, and the length of data
/// starting from that offset to be backed up.
///
///
///
///
/// A ranges file should have been backed up along with the partial file and typically is restored to the same location that it was
/// backed up from.
///
///
/// However, the location to which a ranges file is restored might be altered by the requester, which uses
/// IVssBackupComponents::SetRangesFilePath to indicate this and to update the Backup Components Document so that pbstrRanges
/// indicates the correct ranges file.
///
///
/// A requester would use the ranges information returned by GetPartialFile to restore the backed-up sections to the
/// appropriate location within the copy of the file on disk at restore time.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getpartialfile HRESULT GetPartialFile( [in]
// UINT iPartialFile, [out] BSTR *pbstrPath, [out] BSTR *pbstrFilename, [out] BSTR *pbstrRange, [out] BSTR *pbstrMetadata );
IAppendOnlyList PartialFiles { get; }
///
///
/// The GetPostRestoreFailureMsg method returns the failure message generated by a writer while handling the PostRestore
/// event, if IVssComponent::SetPostRestoreFailureMsg set one.
///
/// Either a writer or a requester can call this method.
///
///
/// Pointer to a string containing the failure message that describes an error that occurred while processing the PostRestore event.
///
///
/// The caller should free the memory held by the pbstrPostRestoreFailureMsg parameter by calling SysFreeString.
/// If SetPostRestoreFailureMsg was not used to set a PostRestore failure message, GetPreRestoreFailureMsg returns S_FALSE.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getpostrestorefailuremsg HRESULT
// GetPostRestoreFailureMsg( [out] BSTR *pbstrPostRestoreFailureMsg );
string PostRestoreFailureMsg { get; set; }
///
/// Returns the PostSnapshot failure message string that a writer has set for a given component.
///
/// Both writers and requesters can call this method. Writers should call this method after the IVssBackupComponents::DoSnapshotSet
/// asynchronous operation has completed.
///
///
///
/// A pointer to a null-terminated wide character string containing the failure message that describes an error that occurred while
/// processing a PostSnapshot event.
///
///
/// The caller is responsible for freeing the string that the pbstrFailureMsg parameter points to by calling the SysFreeString function.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getpostsnapshotfailuremsg HRESULT
// GetPostSnapshotFailureMsg( [out] BSTR *pbstrFailureMsg );
string PostSnapshotFailureMsg { get; set; }
///
/// Returns the PrepareForBackup failure message string that a writer has set for a given component.
/// Both writers and requesters can call this method.
///
///
/// A pointer to a null-terminated wide character string containing the failure message that describes an error that occurred while
/// processing a PrepareForBackup event.
///
///
///
/// The caller is responsible for freeing the string that the pbstrFailureMsg parameter points to by calling the SysFreeString function.
///
/// Examples
///
/// #include <windows.h> #include "vss.h" #include "vsmgmt.h" #define CHKARG_ASSERT(EXPR) do { if(! ( EXPR ) ) { assert(FALSE); hr = E_INVALIDARG; goto exit; } } while ( FALSE, FALSE ); #define CHK(HR) do { hr = ( HR ) ; if(FAILED(HR)) { hr = HR; goto exit; } } while ( FALSE, FALSE ); STDMETHODIMP CheckAsrBackupErrorMsg ( IVssBackupComponents *pBackup, const WCHAR *pwszWriterName ) { CComPtr<IVssWriterComponentsExt> spWriter; CComPtr<IVssComponent> spComponent; CComPtr<IVssComponentEx> spComponentEx; UINT cWriterComponents = 0; UINT iWriterComponent = 0; UINT cComponents = 0; UINT iComponent = 0; VSS_ID idWriter; VSS_ID idInstance; CComBSTR bstrFailureMsg; HRESULT hr = S_OK; CHKARG_ASSERT( pBackup ); CHKARG_ASSERT( pwszWriterName ); CHK( pBackup->GetWriterComponentsCount( &cWriterComponents ) ); for( iWriterComponent = 0; iWriterComponent < cWriterComponents; iWriterComponent++ ) { spWriter.Release(); CHK( pBackup->GetWriterComponents( iWriterComponent, &spWriter ) ); CHK( spWriter->GetWriterInfo(&idInstance, &idWriter) ); if( idWriter != c_ASRWriterId ) { continue; } CHK( spWriter->GetComponentCount(&cComponents) ); for( iComponent = 0; iComponent < cComponents; iComponent++ ) { spComponent.Release(); spComponentEx.Release(); CHK( spWriter->GetComponent(iComponent, &spComponent) ); CHK( spComponent->QueryInterface(__uuidof(IVssComponentEx), (void**)&spComponentEx) ); bstrFailureMsg.Empty(); CHK( spComponentEx->GetPrepareForBackupFailureMsg(&bstrFailureMsg) ); if( ::SysStringLen(bstrFailureMsg) != 0 ) { // Write into the event log. Log_SPP_ERROR_WRITER( &ft, __LINE__, pwszWriterName, bstrFailureMsg ); // The ASR writer writes the same message to all components. // Log the message once. break; } } } exit: return hr; }
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getprepareforbackupfailuremsg HRESULT
// GetPrepareForBackupFailureMsg( [out] BSTR *pbstrFailureMsg );
string PrepareForBackupFailureMsg { get; set; }
///
///
/// The GetPreRestoreFailureMsg method retrieves the error message generated by a writer while handling the PreRestore event,
/// if IVssComponent::SetPreRestoreFailureMsg set one.
///
/// Either a writer or a requester can call this method.
///
/// String containing the failure message that describes an error that occurred while processing the PreRestore event.
///
/// The caller should free the memory held by the pbstrPreRestoreFailureMsg parameter by calling SysFreeString.
/// If SetPreRestoreFailureMsg was not used to set a PreRestore failure message, GetPreRestoreFailureMsg returns S_FALSE.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getprerestorefailuremsg HRESULT
// GetPreRestoreFailureMsg( [out] BSTR *pbstrPreRestoreFailureMsg );
string PreRestoreFailureMsg { get; set; }
///
///
/// The GetPreviousBackupStamp method returns a previous backup stamp loaded by a requester in the Backup Components
/// Document. The value is used by a writer when deciding if files should participate in differential or incremental backup operation.
///
/// Either a writer or a requester can call this method.
///
///
/// Pointer to a string containing the time stamp of a previous backup so that a differential or incremental backup can be correctly implemented.
///
///
///
/// For more information about backup stamps, see Writer Role in Backing Up Complex Stores and Requester Role in Backing Up Complex Stores.
///
/// The caller should free the memory held by the pbstrBackupStamp parameter by calling SysFreeString.
/// If there is no previous backup time stamp, GetPreviousBackupStamp returns S_FALSE.
/// The string returned refers to all files in the component and any nonselectable subcomponents it has.
/// The backup stamp retrieved by GetPreviousBackupStamp is set by a requester using IVssBackupComponents::SetPreviousBackupStamp.
///
/// Typically, the string used to set the value found by GetPreviousBackupStamp was retrieved from a stored Backup Components
/// Document or was stored by the requester as part of its own internal records.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getpreviousbackupstamp HRESULT
// GetPreviousBackupStamp( [out] BSTR *pbstrBackupStamp );
string PreviousBackupStamp { get; }
///
///
/// The GetRestoreMetadata method retrieves private, writer-specific restore metadata that might have been set during a
/// PreRestore event by CVssWriter::OnPreRestore using IVssComponent::SetRestoreMetadata.
///
/// Only a writer can call this method.
///
/// A string containing the restore metadata.
///
/// This method can be called at any time depending on the logic of a given writer.
/// The caller should free the memory held by the pbstrRestoreMetadata parameter by calling SysFreeString.
/// If no backup metadata has been set, GetBackupMetadata returns S_FALSE.
///
/// A writer setting the restore method to VSS_RME_RESTORE_TO_ALTERNATE_LOCATION without defining an alternate location mapping
/// constitutes a writer error.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getrestoremetadata HRESULT
// GetRestoreMetadata( [out] BSTR *pbstrRestoreMetadata );
string RestoreMetadata { get; set; }
/// Obtains the logical name assigned to a component that is being restored.
///
/// The address of a caller-allocated variable that receives a null-terminated wide character string containing the restore name for
/// the component.
///
///
/// The GetRestoreName method can only be called during a restore operation.
///
/// If the call to GetRestoreName is successful, the caller is responsible for freeing the string that is returned in the pbstrName
/// parameter by calling the SysFreeString function.
///
///
/// A writer indicates that it supports this method by setting the VSS_BS_RESTORE_RENAME flag in its backup schema mask.
///
/// For more information, see Setting VSS Restore Options.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getrestorename HRESULT GetRestoreName(
// [out] BSTR *pbstrName );
string RestoreName { get; }
///
/// The GetRestoreOptions method gets the restore options specified to the current writer by a requester using IVssBackupComponents::SetRestoreOptions.
/// Either a writer or a requester can call this method.
///
/// String containing the restore options of the writer.
///
/// The caller should free the memory held by the pbstrRestoreOptions parameter by calling SysFreeString.
/// If no restore options have been set, S_FALSE is returned.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getrestoreoptions HRESULT
// GetRestoreOptions( [out] BSTR *pbstrRestoreOptions );
string RestoreOptions { get; }
///
/// The RestoreSubcomponents property returns the subcomponents associated with a given component.
/// Either a writer or a requester can call this method.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getrestoresubcomponent HRESULT
// GetRestoreSubcomponent( [in] UINT iComponent, [out] BSTR *pbstrLogicalPath, [out] BSTR *pbstrComponentName, [out] bool *pbRepair );
IReadOnlyList RestoreSubcomponents { get; }
///
///
/// The GetRestoreTarget method returns the restore target (in terms of the VSS_RESTORE_TARGET enumeration) for the current component.
///
/// Either a writer or a requester can call this method. It can be called only during a restore operation.
///
///
/// The address of a caller-allocated variable that receives a VSS_RESTORE_TARGET enumeration value that specifies the restore target.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getrestoretarget HRESULT GetRestoreTarget(
// [out] VSS_RESTORE_TARGET *pTarget );
VSS_RESTORE_TARGET RestoreTarget { get; set; }
/// VSS requesters call this method to retrieve component-level errors reported by writers.
///
///
/// The address of a caller-allocated variable that receives the HRESULT failure code that the writer passed for the hr parameter of
/// the IVssComponentEx2::SetFailure method. This parameter is required and cannot be NULL.
///
/// The following are the supported values.
///
///
/// Value
/// Meaning
///
/// -
/// S_OK
/// The writer was successful.
///
/// -
/// VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT
/// The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component.
///
/// -
/// VSS_E_WRITERERROR_OUTOFRESOURCES
///
/// The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes and
/// then repeat the operation, up to three times.
///
///
/// -
/// VSS_E_WRITERERROR_TIMEOUT
///
/// The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this error
/// code is to wait ten minutes and then repeat the operation, up to three times.
///
///
/// -
/// VSS_E_WRITERERROR_RETRYABLE
///
/// The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process was
/// restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times.
///
///
/// -
/// VSS_E_WRITERERROR_NONRETRYABLE
///
/// The writer operation failed because of an error that might recur if another shadow copy is created. For more information, see
/// Event and Error Handling Under VSS.
///
///
/// -
/// VSS_E_WRITER_NOT_RESPONDING
/// The writer is not responding.
///
/// -
/// VSS_E_WRITER_STATUS_NOT_AVAILABLE
///
/// The writer status is not available for one or more writers. A writer may have reached the maximum number of available backup and
/// restore sessions.
///
///
///
///
///
/// The address of a caller-allocated variable that receives the return code that the writer passed for the hrApplication parameter
/// of the SetFailure method. This parameter is required and cannot be NULL.
///
///
/// The address of a caller-allocated variable that receives the application failure message that the writer passed for the
/// wszApplicationMessage parameter of the SetFailure method. This parameter is required and cannot be NULL.
///
///
/// When the caller has finished accessing the status information returned by this method, it should call SysFreeString to free the
/// memory held by the pbstrApplicationMessage parameter.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex2-getfailure HRESULT GetFailure( [out]
// HRESULT *phr, [out] HRESULT *phrApplication, [out] BSTR *pbstrApplicationMessage, [out] DWORD *pdwReserved );
void GetFailure(out HRESULT phr, out HRESULT phrApplication, out string pbstrApplicationMessage);
///
/// Obtains the roll-forward operation type for a component and obtains the restore point for a partial roll-forward operation.
///
/// A VSS_ROLLFORWARD_TYPE enumeration value indicating the type of roll-forward operation to be performed.
///
/// The address of a caller-allocated variable that receives a null-terminated wide character string specifying the roll-forward
/// restore point.
///
///
/// The GetRollForward method can be called only during a restore operation.
///
/// If the call to GetRollForward is successful, the caller is responsible for freeing the string that is returned in the
/// pRollType parameter by calling the SysFreeString function.
///
///
/// A writer indicates that it supports this method by setting the VSS_BS_ROLLFORWARD_RESTORE flag in its backup schema mask.
///
/// For more information, see Setting VSS Restore Options.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getrollforward HRESULT GetRollForward(
// [out] VSS_ROLLFORWARD_TYPE *pRollType, [out] BSTR *pbstrPoint );
void GetRollForward(out VSS_ROLLFORWARD_TYPE pRollType, out string pbstrPoint);
/// VSS writers call this method to report errors at the component level.
///
/// The error code to be returned to the requester that calls the IVssComponentEx2::GetFailure method.
/// The following are the error codes that this method can set.
///
///
/// Value
/// Meaning
///
/// -
/// S_OK
/// The writer was successful.
///
/// -
/// VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT
/// The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component.
///
/// -
/// VSS_E_WRITERERROR_OUTOFRESOURCES
///
/// The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes and
/// then repeat the operation, up to three times.
///
///
/// -
/// VSS_E_WRITERERROR_TIMEOUT
///
/// The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this error
/// code is to wait ten minutes and then repeat the operation, up to three times.
///
///
/// -
/// VSS_E_WRITERERROR_RETRYABLE
///
/// The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process was
/// restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times.
///
///
/// -
/// VSS_E_WRITERERROR_NONRETRYABLE
///
/// The writer operation failed because of an error that might recur if another shadow copy is created. For more information, see
/// Event and Error Handling Under VSS.
///
///
///
///
/// An additional error code to be returned to the requester. This parameter is optional.
///
/// A string containing an error message for the requester to display to the end user. The writer is responsible for localizing this
/// string if necessary before using it in this method. This parameter is optional and can be NULL or an empty string.
///
///
///
/// In addition to calling this method, use the CVssWriterEx2::SetWriterFailureEx method to report that a partial writer failure has occurred.
///
/// This method cannot be called from CVssWriter::OnIdentify or CVssWriterEx::OnIdentifyEx.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex2-setfailure HRESULT SetFailure( [in]
// HRESULT hr, [in] HRESULT hrApplication, [in] LPCWSTR wszApplicationMessage, [in] DWORD dwReserved );
void SetFailure(HRESULT hr, [Optional] HRESULT hrApplication, [Optional] string? wszApplicationMessage);
}
///
///
/// The IVssCreateExpressWriterMetadata interface is a COM interface containing methods to construct the Writer Metadata Document
/// for an express writer.
///
///
/// After it is constructed, the Writer Metadata Document is a read-only object that requesters query for information about a writer and
/// its components.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreateexpresswritermetadata
[PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateExpressWriterMetadata")]
[ComImport, Guid("9c772e77-b26e-427f-92dd-c996f41ea5e3"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IVssCreateExpressWriterMetadata
{
///
/// Excludes a file set (a specified file or files) that might otherwise be implicitly included when a component of an express
/// writer is backed up.
///
///
/// A pointer to a null-terminated wide character string containing the root directory under which files are to be excluded.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (\). It is up to applications that retrieve this information to check.
///
///
///
/// A pointer to a null-terminated wide character string containing the file specification of the files to be excluded.
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
///
///
/// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it
/// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is
/// treated as a hierarchy of directories to be recursed through, or false otherwise.
///
/// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points.
///
///
///
/// Express writers support only local resources—sets of files whose absolute path starts with a valid local volume specification
/// and cannot be a mapped network drive. Therefore, path inputs (wszPath) to AddExcludeFiles (after the resolution of any
/// environment variables) must be in this format. For example, it is often convenient to define a component to include all files in
/// a specified directory and then use AddExcludeFiles to explicitly remove some files (for instance, temporary files) from a backup.
///
/// For more information on excluding files, see Exclude File List Specification.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-addexcludefiles HRESULT
// AddExcludeFiles( [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive );
void AddExcludeFiles([MarshalAs(UnmanagedType.LPWStr)] string wszPath, [MarshalAs(UnmanagedType.LPWStr)] string wszFilespec, bool bRecursive);
/// Adds a file group to an express writer's set of components to be backed up.
///
/// A VSS_COMPONENT_TYPE enumeration value that specifies the type of the component. Only VSS_CT_FILEGROUP is supported for
/// this parameter.
///
///
///
/// A pointer to a null-terminated wide character string containing the logical path of the database or file group. For more
/// information, see Logical Pathing of Components.
///
/// This parameter is optional and can be NULL.
///
///
/// A pointer to a null-terminated wide character string containing the name of the component. This string is not localized.
/// This parameter is required and cannot be NULL. The string cannot contain backslashes.
///
///
///
/// A pointer to a null-terminated wide character string containing a description (also called a "friendly name") for the
/// component. This string might be localized, and therefore requesters must assume that it is localized.
///
/// This parameter is optional and can be NULL. The string can contain backslashes.
///
///
///
/// A pointer to a bitmap of the icon representing the database, to be displayed in a user interface. The size, in bytes, of the
/// buffer is specified by the cbIcon parameter.
///
/// This parameter is optional and can be NULL.
///
/// The number of bytes in .
/// This parameter is reserved for future use and should always be set to false.
/// This parameter is reserved for future use and should always be set to false.
///
/// A Boolean value that indicates whether the component can be optionally backed up (which means it can be excluded from the
/// backup) or is always backed up when any of the writer's components is backed up. This parameter should be set to true if
/// the component can be selectively backed up, or false if the component is backed up when any of the components is backed up.
///
///
///
/// A Boolean value that determines whether a component can be individually restored when it has not been explicitly included in the
/// backup document. If the component was explicitly added to the backup document, it can always be individually selected for
/// restore; in this case, this flag has no meaning.
///
///
/// When this parameter is true, the component can be restored by itself; when false, the component can be restored
/// only if the entire component set is being restored. (For more information, see VSS_COMPONENTINFO and Working with Selectability
/// and Logical Paths.)
///
/// The default value for this parameter is false.
///
///
///
/// A bitmask of VSS_COMPONENT_FLAGS enumeration values indicating the features that this component supports. This bitmask cannot
/// include VSS_CF_APP_ROLLBACK_RECOVERY or VSS_CF_BACKUP_RECOVERY.
///
/// The default value for this parameter is zero.
///
///
/// This method can be called multiple times to add several components to an express writer's metadata.
///
/// The combination of logical path and name for each component of a specified instance of a specified class of writer must be
/// unique. Attempting to call AddComponent twice with the same values of wszLogicalPath and wszComponentName results in a
/// VSS_E_OBJECT_ALREADY_EXISTS error.
///
///
/// AddComponent can be used to add subcomponents—components in which all member files are backed up as a group but which
/// contain files that can be restored individually. For more information, see Working with Selectability for Restore and Subcomponents.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-addcomponent HRESULT
// AddComponent( [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, [in] LPCWSTR wszCaption,
// [in] const BYTE *pbIcon, [in] UINT cbIcon, [in] bool bRestoreMetadata, [in] bool bNotifyOnBackupComplete, [in] bool bSelectable,
// [in] bool bSelectableForRestore, [in] DWORD dwComponentFlags );
void AddComponent(VSS_COMPONENT_TYPE ct, [MarshalAs(UnmanagedType.LPWStr)] string? wszLogicalPath,
[MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.LPWStr)] string? wszCaption,
[Optional] IntPtr pbIcon, uint cbIcon, bool bRestoreMetadata, bool bNotifyOnBackupComplete, bool bSelectable, bool bSelectableForRestore = false,
VSS_COMPONENT_FLAGS dwComponentFlags = 0);
/// Adds a file set (a specified file or files) to a specified file group component for an express writer.
///
/// A pointer to a null-terminated wide character string containing the logical path (which may be NULL) of the
/// component to which to add the files. For more information, see Logical Pathing of Components.
///
///
/// A pointer to a null-terminated wide character string containing the name of the file group component. The type of this
/// component must be VSS_CT_FILEGROUP; otherwise, the method will return an error.
///
///
/// A pointer to a null-terminated wide character string containing the default root directory of the files to be added.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (\). It is up to applications that retrieve this information to check.
///
///
///
/// A pointer to a null-terminated wide character string containing the file specification of the files to be included.
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
///
///
/// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it
/// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is
/// treated as a hierarchy of directories to be recursed through, or false otherwise.
///
/// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points.
///
/// This parameter is reserved and must be NULL.
///
///
/// A bitmask of VSS_FILE_SPEC_BACKUP_TYPE enumeration values to indicate if a writer should evaluate the file for participation in
/// a certain type of backup operations.
///
///
/// This parameter cannot include VSS_FSBT_DIFFERENTIAL_BACKUP_REQUIRED, VSS_FSBT_INCREMENTAL_BACKUP_REQUIRED, or VSS_FSBT_LOG_BACKUP_REQUIRED.
///
/// The default value for this argument is (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED).
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-addfilestofilegroup
// HRESULT AddFilesToFileGroup( [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszGroupName, [in] LPCWSTR wszPath, [in] LPCWSTR
// wszFilespec, [in] bool bRecursive, [in] LPCWSTR wszAlternateLocation, [in] DWORD dwBackupTypeMask );
void AddFilesToFileGroup([MarshalAs(UnmanagedType.LPWStr)] string? wszLogicalPath, [MarshalAs(UnmanagedType.LPWStr)] string wszGroupName,
[MarshalAs(UnmanagedType.LPWStr)] string wszPath, [MarshalAs(UnmanagedType.LPWStr)] string wszFilespec, bool bRecursive,
[MarshalAs(UnmanagedType.LPWStr)] string? wszAlternateLocation = null,
VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED);
/// Specifies how an express writer's data is to be restored.
///
/// A VSS_RESTOREMETHOD_ENUM enumeration value specifying the restore method to be used in the restore operation. This parameter is
/// required and cannot be VSS_RME_UNDEFINED, VSS_RME_RESTORE_TO_ALTERNATE_LOCATION, or VSS_RME_CUSTOM.
///
///
///
/// A pointer to a wide character string containing the name of a service that must be stopped prior to a restore operation and then
/// started after the restore operation takes place, if the value of method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START.
///
///
/// If the value of method is not VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, this parameter is not used
/// and should be set to NULL.
///
///
/// Reserved for future use. The value of this parameter should always be set to NULL.
///
/// A VSS_WRITERRESTORE_ENUM enumeration value specifying whether the writer will be involved in restoring its data. This parameter
/// must be set to VSS_WRE_NEVER.
///
/// A Boolean value indicating whether a reboot will be required after the restore operation is complete.
///
///
/// An express writer can define only one restore method. If the restore method is not overridden, all of the express writer's
/// components will be restored using the same method.
///
///
/// Express writers override the restore method on a component-by-component basis by setting a restore target, typically while
/// handling a PreRestore event (CVssWriter::OnPreRestore).
///
///
/// It is important to note that despite the fact that restore methods are applied on a per-writer basis, methods are implemented on
/// a per-component basis. For example, if the method specified by the method parameter is VSS_RME_RESTORE_IF_CAN_REPLACE,
/// then all of the files in the component are restored to their original location if they can all be replaced without an error
/// occurring. Otherwise, they are restored to their alternate location if one is specified.
///
/// A file can be restored to an alternate location mapping if either of the following is true:
///
/// -
/// The restore method is VSS_RME_RESTORE_IF_NOT_THERE, and a version of the file is already present on disk.
///
/// -
///
/// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE, and a version of the file is present on disk and cannot be replaced.
///
///
///
/// If no valid alternate location mapping is defined, this is a writer error.
/// For more information about restore methods, see Setting VSS Restore Methods.
///
/// If the restore method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, then the correct name of the service must be
/// provided as the wszService argument. For information on writer participation in stopping and restarting services during a
/// restore operation, see Stopping Services for Restore by Requesters.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-setrestoremethod HRESULT
// SetRestoreMethod( [in] VSS_RESTOREMETHOD_ENUM method, [in] LPCWSTR wszService, [in] LPCWSTR wszUserProcedure, [in]
// VSS_WRITERRESTORE_ENUM writerRestore, [in] bool bRebootRequired );
void SetRestoreMethod(VSS_RESTOREMETHOD_ENUM method, [MarshalAs(UnmanagedType.LPWStr)] string? wszService,
[MarshalAs(UnmanagedType.LPWStr)] string? wszUserProcedure, VSS_WRITERRESTORE_ENUM writerRestore, bool bRebootRequired);
///
/// Allows an express writer to indicate that a component it manages has an explicit writer-component dependency; that is, another
/// component (possibly managed by another writer) must be backed up and restored with it.
///
///
/// A null-terminated wide character string containing the logical path of the component (managed by the express writer) that
/// requires a dependency.
///
///
/// A null-terminated wide character string containing the component (managed by the express writer) that requires a dependency.
///
///
/// A VSS_ID (GUID) value that specifies the writer class of the express writer managing the component on which the current
/// component depends.
///
///
/// The logical path of the component (managed by the express writer identified by onWriterId) on which the current component depends.
///
///
/// The name of the component (managed by the express writer identified by onWriterId) on which the current component depends.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-addcomponentdependency
// HRESULT AddComponentDependency( [in] LPCWSTR wszForLogicalPath, [in] LPCWSTR wszForComponentName, [in] VSS_ID onWriterId, [in]
// LPCWSTR wszOnLogicalPath, [in] LPCWSTR wszOnComponentName );
void AddComponentDependency([MarshalAs(UnmanagedType.LPWStr)] string wszForLogicalPath, [MarshalAs(UnmanagedType.LPWStr)] string wszForComponentName,
Guid onWriterId, [MarshalAs(UnmanagedType.LPWStr)] string wszOnLogicalPath, [MarshalAs(UnmanagedType.LPWStr)] string wszOnComponentName);
///
/// Used by an express writer to indicate in its Writer Metadata Document the types of backup operations it can participate in.
///
///
/// A bitmask of VSS_BACKUP_SCHEMA enumeration values that specify the types of backup operations this writer supports.
///
///
///
/// If no schema is explicitly set by SetBackupSchema, the express writer will be assigned the default value of
/// VSS_BS_UNDEFINED. VSS_BS_UNDEFINED means that the writer supports only simple full backup and restoration of
/// entire files (as defined by VSS_BT_FULL), there is no support for incremental or differential backups, and partial files
/// are not supported. Only the VSS_BS_UNDEFINED, VSS_BS_COPY and VSS_BS_INDEPENDENT_SYSTEM_STATE backup schema
/// types are supported by express writers.
///
/// Requesters call IVssExamineWriterMetadata::GetBackupSchema to retrieve a writer's backup schemas as set by SetBackupSchema.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-setbackupschema HRESULT
// SetBackupSchema( [in] DWORD dwSchemaMask );
void SetBackupSchema(VSS_BACKUP_SCHEMA dwSchemaMask);
/// Stores the Writer Metadata Document that contains an express writer's state information into a specified string.
/// A pointer to a string to be used to store the Writer Metadata Document that contains a writer's state information.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-saveasxml HRESULT
// SaveAsXML( [in] BSTR *pbstrXML );
[return: MarshalAs(UnmanagedType.BStr)]
string SaveAsXML();
}
///
///
/// The IVssCreateWriterMetadata interface contains methods to construct the Writer Metadata Document in response to an Identify
/// event. It is used only in the CVssWriter::OnIdentify method.
///
/// The addition and specification of components by a writer is managed through this interface.
///
/// After it is constructed, the Writer Metadata Document is a read-only object that requesters query for information about a writer and
/// its components.
///
/// IVssCreateWriterMetadata defines the following methods.
///
///
/// Method
/// Description
///
/// -
/// AddAlternateLocationMapping
/// Creates an alternate location mapping.
///
/// -
/// AddComponent
/// Adds a database or file group as a component to be backed up.
///
/// -
/// AddComponentDependency
///
/// Indicates that a component participates in a backup or restore only if specified components managed by other writers also participate.
///
///
/// -
/// AddDatabaseFiles
/// Indicates the physical files that are associated with a database to be backed up, as well as their location.
///
/// -
/// AddDatabaseLogFiles
/// Indicates the log files that are associated with a database to be backed up, as well as their location.
///
/// -
/// AddExcludeFiles
/// Specifies the files that will be excluded from the backup.
///
/// -
/// AddFilesToFileGroup
/// Adds the specified file or files to the specified file group.
///
/// -
/// AddIncludeFiles
/// Reserved for system use.
///
/// -
/// GetDocument
/// Reserved for system use.
///
/// -
/// SaveAsXML
/// Saves a text string containing the Writer Metadata Document.
///
/// -
/// SetBackupSchema
/// Sets the backup schema (how a backup is to be executed) to be used when processing a writer's files.
///
/// -
/// SetRestoreMethod
/// Indicates how writer data is to be restored.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreatewritermetadata
[PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateWriterMetadata")]
public interface IVssCreateWriterMetadata
{
/// The AddAlternateLocationMapping method creates an alternate location mapping for a file set.
///
/// String containing the name of the directory or directory hierarchy containing the files to be mapped.
/// The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.
///
///
///
/// String containing the file specification of the files to be mapped.
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
///
///
/// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it
/// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is
/// treated as a hierarchy of directories to be traversed recursively, or false if not.
///
/// For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points.
///
///
/// String containing the fully qualified path to the directory where the files will be relocated.
/// The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.
/// UNC paths are supported.
///
///
///
/// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: Remote file
/// shares are not supported until Windows 8 and Windows Server 2012. Writers support only local resources—sets of files whose
/// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs
/// (wszPath and wszDestination) to AddAlternateLocationMapping (after the resolution of any environment variables) must be
/// in this format.
///
/// This method can be called multiple times to add mapping for multiple files.
///
/// The combination of path, file specification, and recursion flag (wszPath, wszFileSpec, and bRecursive, respectively) provided to
/// AddAlternateLocationMapping to be mapped must match that of one of the file sets added to one of the writer's components
/// using IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles.
///
///
/// The AddAlternateLocationMapping method should be called only after IVssCreateWriterMetadata::SetRestoreMethod is called.
///
/// A file should always be restored to its alternate location mapping if either of the following is true:
///
/// -
/// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION.
///
/// -
/// Its restore target was set (at restore time) to VSS_RT_ALTERNATE.
///
///
/// In either case, if no valid alternate location mapping is defined, this constitutes a writer error.
/// A file can be restored to an alternate location mapping if either of the following is true:
///
/// -
/// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk.
///
/// -
/// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced.
///
///
/// Again, if no valid alternate location mapping is defined, this constitutes a writer error.
///
/// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which
/// is used only during a backup operation.
///
/// For more information on backup and restore file locations under VSS, see Non-Default Backup And Restore Locations.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addalternatelocationmapping
// HRESULT AddAlternateLocationMapping( [in] LPCWSTR wszSourcePath, [in] LPCWSTR wszSourceFilespec, [in] bool bRecursive, [in]
// LPCWSTR wszDestination );
void AddAlternateLocationMapping(string wszSourcePath, string wszSourceFilespec, bool bRecursive, string wszDestination);
/// The AddComponent method adds a database or file group as a component to be backed up.
///
/// A VSS_COMPONENT_TYPE enumeration value specifying the type of the component.
///
/// Windows Server 2003 and Windows XP: Before Windows Server 2003 with SP1, this parameter is reserved for system use, and
/// the caller should not override the default value.
///
///
///
///
/// A pointer to a null-terminated wide character string containing the logical path of the database or file group. For more
/// information, see Logical Pathing of Components.
///
/// A logical path is optional and can be NULL.
///
///
/// A pointer to a null-terminated wide character string containing the name of the component. This string is not localized.
/// This parameter is required and cannot be NULL. The string cannot contain backslashes.
///
///
///
/// A pointer to a null-terminated wide character string containing a description (also called a "friendly name") for the
/// component. This string might be localized, and therefore requesters must assume that it is localized.
///
/// This parameter is optional and can be NULL. The string can contain backslashes.
///
///
///
/// A pointer to a bitmap of the icon representing the database, to be displayed in a user interface. The size, in bytes, of the
/// buffer is specified by the cbIcon parameter.
///
/// If the writer does not want to specify an icon, pbIcon should be set to NULL.
///
/// This parameter is reserved for future use and should always be set to false.
/// This parameter is reserved for future use and should always be set to false.
///
/// A Boolean that indicates whether the component can be optionally backed up (which means it can be excluded from the backup) or
/// is always backed up when any of the writer's component is backed up. The Boolean is true if the component can be
/// selectively backed up and false if it is backed up when any of the components is backed up.
///
///
///
/// A Boolean that determines whether a component can be individually restored when it has not been explicitly included in the
/// backup document. If the component was explicitly added to the backup document, it can always be individually selected for
/// restore; in this case, this flag has no meaning.
///
///
/// When true, the component can be restored by itself; when false, the component can be restored only if the entire
/// component set is being restored. (See VSS_COMPONENTINFO and Working with Selectability and Logical Paths for more information).
///
/// The default value for this parameter is false.
///
///
///
/// A bit mask (or bitwise OR) of members of the VSS_COMPONENT_FLAGS enumeration indicating the features that this component supports.
///
/// The default value for this argument is zero.
///
///
/// This method can be called multiple times to add several components to a writer's metadata.
///
/// The combination of logical path and name for each component of a given instance of a given class of writer must be unique.
/// Attempting to call AddComponent twice with the same values of wszLogicalPath and wszComponentName results in a
/// VSS_E_OBJECT_ALREADY_EXISTS error.
///
///
/// AddComponent can be used to add subcomponents—components in which all member files are backed up as a group, but which
/// contain files that can be restored individually. See Working with Selectability for Restore and Subcomponents for more information.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addcomponent HRESULT
// AddComponent( [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, [in] LPCWSTR wszCaption,
// [in] const BYTE *pbIcon, [in] UINT cbIcon, [in] bool bRestoreMetadata, [in] bool bNotifyOnBackupComplete, [in] bool bSelectable,
// [in] bool bSelectableForRestore, [in] DWORD dwComponentFlags );
void AddComponent(VSS_COMPONENT_TYPE ct, [Optional] string? wszLogicalPath, string wszComponentName, [Optional] string? wszCaption, byte[]? pbIcon,
bool bRestoreMetadata, bool bNotifyOnBackupComplete, bool bSelectable, bool bSelectableForRestore = false,
VSS_COMPONENT_FLAGS dwComponentFlags = 0);
///
/// The AddComponentDependency method allows a writer to indicate that a component it manages has an explicit
/// writer-component dependency; that is, another component in another writer must be backed up and restored with it.
///
///
/// A null-terminated wide character string containing the logical path of the component (managed by the current writer) that
/// requires a dependency.
///
///
/// A null-terminated wide character string containing the component (managed by the current writer) that requires a dependency.
///
///
/// The class ID or VSS_ID (GUID) of the writer managing the component on which the current component depends.
///
///
/// The logical path of the component (managed by the writer identified by onWriterId) on which the current component depends.
///
///
/// The name of the component (managed by the writer identified by onWriterId) on which the current component depends.
///
///
/// Dependencies upon components managed by the current writer are not permitted.
///
/// A dependency requires that both the target of the dependency and the component that depends on the target be restored and backed
/// up together. It does not indicate a priority between the components, although a requester may choose to implement that.
///
///
/// Because the combination of logical name and component name must be unique across all instances of a writer class, the fact that
/// several writers may have the same class ID is not a problem.
///
///
/// This method can be used to declare remote dependencies. A writer can declare a remote dependency by prepending
/// "\\RemoteComputerName", where RemoteComputerName is the name of the computer where the remote component resides, to the logical
/// path in the wszOnLogicalPath parameter. The value of RemoteComputerName can be an IP address or a computer name returned by the
/// GetComputerNameEx function.
///
///
/// If the remote component resides on a cluster, the writer must report the virtual name for the cluster, and it is the requester's
/// responsibility to map the virtual name to the physical name of a cluster node before a volume shadow copy can be created.
///
///
/// To determine whether a dependency is local or remote, the requester must examine the component name returned in the
/// pbstrComponentName parameter. If the component name begins with "\", the requester must assume that it specifies a remote
/// dependency and that the first component following "\" is the RemoteComputerName that was specified by the writer. If the
/// component name does not begin with "\", the requester should assume that it specifies a local dependency.
///
///
/// Windows Server 2003: This method cannot be used to declare remote dependencies until Windows Server 2003 with Service
/// Pack 1 (SP1).
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addcomponentdependency HRESULT
// AddComponentDependency( [in] LPCWSTR wszForLogicalPath, [in] LPCWSTR wszForComponentName, [in] VSS_ID onWriterId, [in] LPCWSTR
// wszOnLogicalPath, [in] LPCWSTR wszOnComponentName );
void AddComponentDependency(string wszForLogicalPath, string wszForComponentName, Guid onWriterId, string wszOnLogicalPath,
string wszOnComponentName);
///
/// The AddDatabaseFiles method indicates the file set (the specified file or files) that make up the database component to
/// be backed up.
///
///
///
/// Pointer to a null-terminated wide character string containing the logical path of the component to which the database
/// will be added.
///
/// For more information, see Logical Pathing of Components.
/// A logical path is not required and can be NULL.
///
///
/// Pointer to a null-terminated wide character string containing the name of the database.
/// This name is required and must match the name of the component to which the database is being added.
///
///
///
/// Pointer to a null-terminated wide character string containing the path of the directory containing the database file.
///
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
/// UNC paths are supported.
///
/// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.
///
///
///
///
/// Pointer to a null-terminated wide character string containing the file specification of the file or files associated with
/// the database.
///
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
///
///
/// A bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE enumeration values to indicate whether a writer should evaluate the file
/// for participation in certain types of backup operations.
///
/// The default value for this argument is (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED).
///
///
///
/// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: Remote file
/// shares are not supported until Windows 8 and Windows Server 2012. Writers support only local resources—sets of files whose
/// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs
/// (wszPath) to AddDatabaseFiles (after the resolution of any environment variables) must be in this format.
///
///
/// This method can be called multiple times for a particular database. This is done when the database exists on files stored on
/// separate volumes, as is possible with Microsoft SQL Server.
///
///
/// The values of the wszLogicalPath and wszDatabaseName parameters should match those of one of the database components previously
/// added with the IVssCreateWriterMetadata::AddComponent method.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-adddatabasefiles HRESULT
// AddDatabaseFiles( [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszDatabaseName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in]
// DWORD dwBackupTypeMask );
void AddDatabaseFiles([Optional] string? wszLogicalPath, string wszDatabaseName, string wszPath, string wszFilespec,
VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED);
///
/// The AddDatabaseLogFiles method indicates the log files that are associated with a database to be backed up, as well as
/// their location.
///
///
///
/// Pointer to a null-terminated wide character string containing the logical path of the database component to which the log
/// files will be added.
///
/// For more information, see Logical Pathing of Components.
/// A logical path is not required, and can be NULL.
///
///
/// Pointer to a null-terminated wide character string containing the name of the database component associated with the log
/// files. The type of this component must be VSS_CT_DATABASE; otherwise, the method will return an error.
///
///
/// Pointer to a null-terminated wide character string containing the path of the directory containing the log files.
/// The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.
/// UNC paths are supported.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.
///
///
///
///
/// Pointer to a null-terminated wide character string containing the file specification of the log file(s) associated with
/// the database.
///
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
///
///
/// A bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE enumeration values to indicate if a writer should evaluate the file for
/// participation in a certain type of backup operations.
///
/// The default value for this argument is (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED).
///
///
///
/// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: Remote file
/// shares are not supported until Windows 8 and Windows Server 2012. Writers support only local resources—sets of files whose
/// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs
/// (wszPath) to AddDatabaseLogFiles (after the resolution of any environment variables) must be in this format.
///
///
/// This method can be called multiple times for a particular database component, which might be needed when several log files are
/// stored on separate volumes.
///
///
/// The values of the wszLogicalPath and wszDatabaseName parameters should match those of one of the database components previously
/// added with the IVssCreateWriterMetadata::AddComponent method.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-adddatabaselogfiles HRESULT
// AddDatabaseLogFiles( [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszDatabaseName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec,
// [in] DWORD dwBackupTypeMask );
void AddDatabaseLogFiles([Optional] string? wszLogicalPath, string wszDatabaseName, string wszPath, string wszFilespec,
VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED);
///
/// The AddExcludeFiles method is used to explicitly exclude a file set (a specified file or files) that might otherwise be
/// implicitly included when a component of the current writer is backed up.
///
///
/// Pointer to a null-terminated wide character string containing the root directory under which files are to be excluded.
/// The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.
/// UNC paths are supported.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.
///
///
///
/// Pointer to a null-terminated wide character string containing the file specification of the files to be excluded.
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
///
///
/// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it
/// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is
/// treated as a hierarchy of directories to be recursed through, or false otherwise.
///
/// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points.
///
///
///
/// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: Remote file
/// shares are not supported until Windows 8 and Windows Server 2012. Writers support only local resources—sets of files whose
/// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs
/// (wszPath) to AddExcludeFiles (after the resolution of any environment variables) must be in this format.
///
///
/// For example, it is often convenient to define a component to include all files in a given directory and then use
/// AddExcludeFiles to explicitly remove some files (for instance, temporary files) from a backup.
///
/// For more information on excluding files, see Exclude File List Specification.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addexcludefiles HRESULT
// AddExcludeFiles( [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive );
void AddExcludeFiles(string wszPath, string wszFilespec, bool bRecursive);
/// The AddFilesToFileGroup method adds a file set (a specified file or files) to a specified file group component.
///
/// Pointer to a null-terminated wide character string containing the logical path (which may be NULL) of the
/// component to which to add the files. For more information, see Logical Pathing of Components.
///
///
/// Pointer to a null-terminated wide character string containing the name of the file group component. The type of this
/// component must be VSS_CT_FILEGROUP; otherwise, the method will return an error.
///
///
/// Pointer to a null-terminated wide character string containing the default root directory of the files to be added.
/// The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.
/// UNC paths are supported.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.
///
///
///
/// Pointer to a null-terminated wide character string containing the file specification of the files to be included.
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
///
///
/// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it
/// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is
/// treated as a hierarchy of directories to be recursed through, or false otherwise.
///
/// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points.
///
///
///
/// Pointer to a null-terminated wide character string containing the alternate path, which actually contains the files to be
/// backed up with this component.
///
/// The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.
/// UNC paths are supported.
/// Specifying an alternate path is optional; if no alternate path is needed, wszAlternatePath should be NULL.
/// An alternate path should not be confused with an alternate location mapping.
///
///
///
/// A bitmask of VSS_FILE_SPEC_BACKUP_TYPE enumeration values to indicate if a writer should evaluate the file for participation in
/// a certain type of backup operations.
///
/// The default value for this argument is (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED).
///
///
///
/// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: Remote file
/// shares are not supported until Windows 8 and Windows Server 2012. Writers support only local resources—sets of files whose
/// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs
/// (wszPath and wszAlternatePath) to AddFilesToFileGroup (after the resolution of any environment variables) must be in this format.
///
///
/// A writer can call this method multiple times to add several sets of files to its file group component. However, you should make
/// sure that the file specifications do not overlap, because a particular file can be specified only once.
///
///
/// The locations from which files are backed up and to which they are restored depends on the values for the root directory defined
/// by wszPath and the alternate path defined by wszAlternatePath.
///
/// Note the following when using path information provided by AddFilesToFileGroup:
///
/// -
///
/// Restore operations should (if possible) restore files added to a component by AddFilesToFileGroup under the default root
/// directory defined by wszPath.
///
///
/// -
///
/// If an alternate path is not specified (if wszAlternatePath is NULL), the files added to the component will be backed up
/// from the default root directory and restored to the default root directory indicated by wszPath.
///
///
/// -
///
/// If an alternate path is specified (if wszAlternatePath is non- NULL), files added to the component are backed up from the
/// alternate path specified by wszAlternatePath. However, requesters will still use wszPath as the default restoration location.
///
///
/// -
///
/// If the alternate path is defined (wszAlternatePath is non- NULL) and there are files matching the file specification
/// (wszFilespec) in both the alternate path and the default root directory (wszPath), then a backup operation should back up files
/// located under the alternate path, not files located under the default root directory.
///
///
/// -
///
/// Files should be restored to the directory indicated by wszPath unless an alternate location mapping was set by
/// IVssCreateWriterMetadata::AddAlternateLocationMapping and the restore method or restore target requires it.
///
///
///
/// For more information on backup and restore file locations under VSS, see Non-Default Backup And Restore Locations.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addfilestofilegroup HRESULT
// AddFilesToFileGroup( [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszGroupName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in]
// bool bRecursive, [in] LPCWSTR wszAlternateLocation, [in] DWORD dwBackupTypeMask );
void AddFilesToFileGroup([Optional] string? wszLogicalPath, string wszGroupName, string wszPath, string wszFilespec, bool bRecursive,
[Optional] string? wszAlternateLocation,
VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED);
///
/// The SaveAsXML method saves the Writer Metadata Document that contains a writer's state information to a specified string.
///
/// Pointer to a string to be used to store the Writer Metadata Document that contains a writer's state information.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-saveasxml HRESULT SaveAsXML(
// [in] BSTR *pbstrXML );
string SaveAsXML();
///
/// The SetBackupSchema method is used by a writer to indicate in its Writer Metadata Document the types of backup operations
/// it can participate in.
///
///
/// The types of backup operations this writer supports expressed as a bitmask of VSS_BACKUP_SCHEMA enumeration values.
///
/// For express writers, only the VSS_BS_UNDEFINED, VSS_BS_COPY, and VSS_BS_INDEPENDENT_SYSTEM_STATE values are supported.
///
///
///
///
/// If no schema is explicitly set by SetBackupSchema, the writer will be assigned the default value of VSS_BS_UNDEFINED: the
/// writer supports only simple full backup and restoration of entire files (as defined by VSS_BT_FULL), there is no support for
/// incremental or differential backups, and partial files are not supported.
///
/// Requesters call IVssExamineWriterMetadata::GetBackupSchema to retrieve a writer's backup schemas as set by SetBackupSchema.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-setbackupschema HRESULT
// SetBackupSchema( [in] DWORD dwSchemaMask );
void SetBackupSchema(VSS_BACKUP_SCHEMA dwSchemaMask);
/// The SetRestoreMethod method indicates how the writer's data is to be restored.
/// VSS_RESTOREMETHOD_ENUM value specifying the method that will be used in the restore operation.
///
///
/// A pointer to a wide character string containing the name of a service that must be stopped prior to a restore operation and then
/// started after the restore operation takes place, if the value of method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START.
///
///
/// If the value of method is not VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, this argument is not used and should be
/// set to NULL.
///
///
/// Reserved for future use. The value of this parameter should always be set to NULL.
///
/// VSS_WRITERRESTORE_ENUM value specifying whether the writer will be involved in restoring its data.
/// Express writers must set this parameter to VSS_WRE_NEVER.
///
/// Boolean indicating whether a reboot will be required after the restore operation is complete.
///
///
/// There is a single restore method defined for a writer. If the restore method is not overridden, all of the writer's components
/// will be restored using the same method.
///
///
/// Writers override the restore method on a component-by-component basis by setting a restore target, typically while handling a
/// PreRestore event (CVssWriter::OnPreRestore).
///
///
/// It is important to note that despite the fact that restore methods are applied writer-wide, methods are implemented on a
/// per-component basis. For example, if the method specified by the method parameter is VSS_RME_RESTORE_IF_CAN_REPLACE, then all of
/// the files in the component are restored to their original location if they can all be replaced without an error occurring.
/// Otherwise, they are restored to their alternate location if one is specified.
///
/// A file should always be restored to its alternate location mapping if either of the following is true:
///
/// -
/// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION.
///
/// -
/// Its restore target was set (at restore time) to VSS_RT_ALTERNATE.
///
///
/// In either case, if no valid alternate location mapping is defined, this constitutes a writer error.
/// A file can be restored to an alternate location mapping if either of the following is true:
///
/// -
/// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk.
///
/// -
/// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced.
///
///
/// Again, if no valid alternate location mapping is defined, this constitutes a writer error.
///
/// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which
/// is used only during a backup operation.
///
/// For more information about restore methods, see Setting VSS Restore Methods.
///
/// If the restore method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, then the correct name of the service must be
/// provided as the wszService argument. For information on writer participation in stopping and restarting services during a
/// restore operation, see Stopping Services for Restore by Requesters.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-setrestoremethod HRESULT
// SetRestoreMethod( [in] VSS_RESTOREMETHOD_ENUM method, [in] LPCWSTR wszService, [in] LPCWSTR wszUserProcedure, [in]
// VSS_WRITERRESTORE_ENUM writerRestore, [in] bool bRebootRequired );
void SetRestoreMethod(VSS_RESTOREMETHOD_ENUM method, [Optional] string? wszService, [Optional] string? wszUserProcedure,
VSS_WRITERRESTORE_ENUM writerRestore, bool bRebootRequired);
}
///
///
/// The IVssCreateWriterMetadataEx interface defines a method to report any file sets that will be explicitly excluded when a
/// shadow copy is created. This interface is used only in the CVssWriterEx::OnIdentifyEx method.
///
/// The IVssCreateWriterMetadataEx interface inherits from the IVssCreateWriterMetadata interface and IUnknown.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreatewritermetadataex
[PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateWriterMetadataEx")]
public interface IVssCreateWriterMetadataEx : IVssCreateWriterMetadata
{
///
/// Reports any file sets that will be explicitly excluded by the writer when a shadow copy is created.
///
/// Calling this method does not cause the files to be excluded. The writer is responsible for deleting the files from the shadow
/// copy in its CVssWriter::OnPostSnapshot method.
///
///
///
/// A pointer to a null-terminated wide character string containing the root directory under which files are to be excluded.
/// The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.
/// UNC paths are supported.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to
/// check whether the path ends with a backslash.
///
///
///
/// A pointer to a null-terminated wide character string containing the file specification of the files to be excluded.
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
///
///
/// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it
/// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is
/// treated as a hierarchy of directories to be recursed through, or false otherwise.
///
/// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points.
///
///
///
/// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: Remote file
/// shares are not supported until Windows 8 and Windows Server 2012.
///
///
/// The use of the AddExcludeFilesFromSnapshot method is optional. Writers should use this method only for large files that
/// change significantly between shadow copy operations.
///
///
/// This method is not a substitute for the IVssCreateWriterMetadata::AddExcludeFiles method. Writers should continue to use the
/// AddExcludeFiles method to report which file sets are excluded from backup.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadataex-addexcludefilesfromsnapshot
// HRESULT AddExcludeFilesFromSnapshot( [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive );
void AddExcludeFilesFromSnapshot(string wszPath, string wszFilespec, bool bRecursive);
}
/// Defines methods to manage metadata for a VSS express writer.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivssexpresswriter
[PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssExpressWriter")]
public interface IVssExpressWriter
{
/// Creates an express writer metadata object and returns an IVssCreateExpressWriterMetadata interface pointer to it.
/// The globally unique identifier (GUID) of the writer class.
///
/// A null-terminated wide character string that contains the name of the writer class. This string is not localized.
///
///
/// A VSS_USAGE_TYPE enumeration value that indicates how the data that is managed by the writer is used on the host system. The
/// only valid values for this parameter are VSS_UT_BOOTABLESYSTEMSTATE, VSS_UT_SYSTEMSERVICE, and VSS_UT_USERDATA.
///
/// The major version of the writer application. For more information, see the Remarks section.
/// The minor version of the writer application. For more information, see the Remarks section.
///
/// A pointer to a variable that receives an IVssCreateExpressWriterMetadata interface pointer to the newly created express writer metadata.
///
///
///
/// The versionMajor and versionMajor parameters are used to specify the writer's major and minor version numbers according to the
/// following VSS conventions:
///
///
/// -
///
/// A writer's minor version number should be incremented by one whenever a released version of the writer contains minor changes
/// that affect the writer's interaction with requesters. For example, a correction to a file specification in a writer QFE or
/// service pack would justify incrementing the minor version number. However, a change between beta or release candidate versions
/// of a writer would not justify the changing of the minor version number.
///
///
/// -
///
/// A writer's major version number should be incremented by one whenever a released version of the writer contains a significant
/// change. For example, if data that is backed up with a new version of a writer cannot be restored using the previous version of
/// the writer, the new writer's major version number should be incremented.
///
///
/// -
/// Whenever the major version number is incremented, the minor version number should be reset to zero.
///
///
/// If a writer does not specify a version number, VSS will assign a default version number of 0.0.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivssexpresswriter-createmetadata HRESULT CreateMetadata(
// [in] VSS_ID writerId, [in] LPCWSTR writerName, [in] VSS_USAGE_TYPE usageType, [in] DWORD versionMajor, [in] DWORD versionMinor,
// [in] DWORD reserved, [out] IVssCreateExpressWriterMetadata **ppMetadata );
IVssCreateExpressWriterMetadata CreateMetadata(Guid writerId, string writerName, VSS_USAGE_TYPE usageType, uint versionMajor, uint versionMinor);
/// Causes VSS to load the writer's metadata from a string instead of the express writer metadata store.
/// A null-terminated wide character string that contains the writer's metadata.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivssexpresswriter-loadmetadata HRESULT LoadMetadata( [in]
// LPCWSTR metadata, [in] DWORD reserved );
void LoadMetadata(string metadata);
/// Causes VSS to store the writer's metadata in the express writer metadata store.
///
/// Before using this method, the caller must have either used the LoadMetadata method to load the writer's metadata directly or
/// used the CreateMetadata method to create a writer metadata object.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivssexpresswriter-register HRESULT Register();
void Register();
/// Causes VSS to delete the writer's metadata from the express writer metadata store.
/// The globally unique identifier (GUID) of the writer class.
/// Before using this method, the caller must have used the CreateMetadata method to create a writer metadata object.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivssexpresswriter-unregister HRESULT Unregister( [in]
// VSS_ID writerId );
void Unregister(Guid writerId);
}
///
///
/// The IVssWMDependency is returned by the IVssWMComponent interface and used by applications when backing up or restoring a
/// component that has an explicit writer-component dependency on a component managed by another writer. (Dependencies must be between
/// writers, not within writers.)
///
///
/// IVssWMDependency is used to determine the writer ID, logical path, and component name of components that must be restored or
/// backed up along with the target component.
///
///
/// Dependencies are created by writers while handling Identify events (CVssWriter::OnIdentify) using the
/// IVssCreateWriterMetadata::AddComponentDependency method.
///
/// The IVssWMComponent::GetDependency method returns an IVssWMDependency interface.
///
/// Note that a dependency does not indicate an order of preference between the component with the documented dependencies and the
/// components it depends on. A dependency merely indicates that the component and the components it depends on must always be backed up
/// or restored together.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswmdependency
[PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWMDependency")]
public interface IVssWMDependency
{
///
/// The GetComponentName method retrieves the name of a component that the current component depends on in an explicit
/// writer-component dependency.
///
///
/// The address of a caller-allocated variable that receives a NULL-terminated wide character string containing the name of
/// the component that the current component depends on.
///
///
/// The caller must free the memory used by the returned string by calling SysFreeString.
///
/// A dependency does not indicate an order of preference between the component with the documented dependencies and the components
/// it depends on. A dependency merely indicates that the component and the components it depends on must always be backed up or
/// restored together.
///
///
/// It is possible to have multiple instances of a given writer class; however, any component's logical path and name should be unique.
///
///
/// If there are multiple instances of a writer class, it will be necessary to use logical path and component name information to
/// identify the instance managing the component that the current component depends on.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmdependency-getcomponentname HRESULT
// GetComponentName( BSTR *pbstrComponentName );
string ComponentName { get; }
///
/// The GetLogicalPath method retrieves the logical path of a component that the current component depends on in explicit
/// writer-component dependency.
///
///
/// The address of a caller-allocated variable that receives a NULL-terminated wide character string containing the logical
/// path of the component that the current component depends on.
///
///
/// The caller must free the memory used by the returned string by calling SysFreeString.
///
/// A dependency does not indicate an order of preference between the component with the documented dependencies and the components
/// it depends on. A dependency merely indicates that the component and the components it depends on must always be backed up or
/// restored together.
///
///
/// It is possible to have multiple instances of a given writer class; however, any component's logical path and name should be unique.
///
///
/// If there are multiple instances of a writer class, it will be necessary to use logical path and component name information to
/// identify the instance managing the component that the current component depends on.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmdependency-getlogicalpath HRESULT GetLogicalPath(
// [out] BSTR *pbstrLogicalPath );
string LogicalPath { get; }
///
/// The GetWriterId method retrieves the class ID of a writer containing a component that the current component depends on in
/// an explicit writer-component dependency.
///
/// The class ID of a writer that manages a component on which the current component depends.
///
///
/// A dependency does not indicate an order of preference between the component with the documented dependencies and the components
/// it depends on. A dependency merely indicates that the component and the components it depends on must always be backed up or
/// restored together.
///
///
/// It is possible to have multiple instances of a given writer class; however, any component's logical path and name should be unique.
///
///
/// If there are multiple instances of a writer class, it will be necessary to use logical path and component name information to
/// identify the instance managing the component that the current component depends on.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmdependency-getwriterid HRESULT GetWriterId( VSS_ID
// *pWriterId );
Guid WriterId { get; }
}
///
///
/// The IVssWMFiledesc interface is returned to a calling application by a number of query methods. It provides detailed
/// information about a file or set of files (a file set).
///
/// The following methods return an IVssWMFiledesc interface:
///
/// -
/// IVssComponent::GetAlternateLocationMapping
///
/// -
/// IVssComponent::GetNewTarget
///
/// -
/// IVssExamineWriterMetadata::GetExcludeFile
///
/// -
/// IVssExamineWriterMetadata::GetAlternateLocationMapping
///
/// -
/// IVssWMComponent::GetFile
///
/// -
/// IVssWMComponent::GetDatabaseFile
///
/// -
/// IVssWMComponent::GetDatabaseLogFile
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswmfiledesc
[PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWMFiledesc")]
public interface IVssWMFiledesc
{
/// The GetAlternateLocation method obtains an alternate location for a file set.
///
/// The address of a caller-allocated variable that receives a string specifying the alternate backup location. The path of this
/// location can be a local path or the UNC path of a remote file share. If there is no alternate location, the pointer is NULL.
///
///
///
/// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: Remote file
/// shares are not supported until Windows 8 and Windows Server 2012.
///
/// The caller must call SysFreeString to free the memory held by the pbstrAlternateLocation parameter.
///
/// The interpretation of the alternate location returned by GetAlternateLocation differs depending on the method used to
/// retrieve the IVssWMFiledesc object.
///
///
/// -
/// IVssExamineWriterMetadata::GetExcludeFile
///
/// -
/// IVssWMComponent::GetDatabaseFile
///
/// -
/// IVssWMComponent::GetDatabaseLogFile
///
/// -
/// IVssWMComponent::GetFile
///
///
///
/// The value returned by GetAlternateLocation refers to an alternate location mapping when returned by the
/// IVssExamineWriterMetadata::GetAlternateLocationMapping method.
///
///
/// During backup operations, this is the alternate location from which to back up a file. During a restore, it is the alternate
/// location to which to restore a file.
///
/// For more information, see Non-Default Backup And Restore Locations.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getalternatelocation HRESULT
// GetAlternateLocation( [out] BSTR *pbstrAlternateLocation );
string? AlternateLocation { get; }
///
/// The GetBackupTypeMask method returns the file backup specification for the files specified by the current file descriptor
/// as a bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE values. This information indicates if the files are to be evaluated
/// by their writer for participation in various specific types of backup operations (or if they will participate in an incremental
/// or differential backups).
///
///
/// Pointer to a DWORD containing a bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE values indicating the file backup
/// specification for the file or file set described by the current IVssWMFiledesc interface.
///
///
/// A file backup specification is specified by a writer when it adds a file specification to a component using the
/// IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or
/// IVssCreateWriterMetadata::AddDatabaseLogFiles method.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getbackuptypemask HRESULT
// GetBackupTypeMask( DWORD *pdwTypeMask );
VSS_FILE_SPEC_BACKUP_TYPE BackupTypeMask { get; }
///
///
/// The GetFilespec method returns the file specification used to obtain the list of files that the current IVssWMFiledesc
/// object is a member of.
///
/// A querying method used a path and this file specification to return the current IVssWMFiledesc object.
///
///
/// The address of a caller-allocated variable that receives a string specifying the returned file specification.
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
/// The caller must call SysFreeString to free the memory held by the pbstrFilespec parameter.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getfilespec HRESULT GetFilespec( [out]
// BSTR *pbstrFilespec );
string FileSpec { get; }
///
///
/// The GetPath method obtains the fully qualified directory path or the UNC path of the remote file share to obtain the list
/// of files described in the current IVssWMFiledesc object.
///
/// A querying method used this path and a file specification to return the current IVssWMFiledesc object.
///
///
///
/// The address of a caller-allocated variable that receives a NULL-terminated wide character string specifying the fully
/// qualified directory path or the UNC path of the remote file share directory.
///
/// The path can be a long or short file name and can use the prefix "\?". For more information, see Naming a File.
/// Users of this method need to check to determine whether this path ends with a backslash ("").
///
///
///
/// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: Remote file
/// shares are not supported until Windows 8 and Windows Server 2012.
///
/// The caller must call SysFreeString to free the memory held by the pbstrPath parameter.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getpath HRESULT GetPath( [out] BSTR
// *pbstrPath );
string Path { get; }
///
/// The GetRecursive method indicates whether the list of files described in a IVssWMFiledesc object with a root directory
/// returned by IVssWMFiledesc::GetPath contains only files in that directory or whether the file list contains files from the
/// directory hierarchy as well.
///
///
///
/// A pointer to a Boolean value specifying whether the value returned by IVssWMFiledesc::GetPath identifies only a single directory
/// or if it indicates a hierarchy of directories to be traversed recursively. The Boolean value receives true if the path is
/// treated as a hierarchy of directories to be traversed recursively, or false if not.
///
/// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getrecursive HRESULT GetRecursive( [out]
// bool *pbRecursive );
bool Recursive { get; }
}
///
///
/// The IVssWriterComponents interface contains methods used to obtain and modify component information (in the form of
/// IVssComponent objects) associated with a given writer but stored in a requester's Backup Components Document.
///
///
/// The CVssWriter base class is responsible for passing an instance of the IVssWriterComponents interface to the following event handlers:
///
///
/// -
/// CVssWriter::OnPrepareBackup
///
/// -
/// CVssWriter::OnBackupComplete
///
/// -
/// CVssWriter::OnPreRestore
///
/// -
/// CVssWriter::OnPostRestore
///
/// -
/// CVssWriter::OnPostSnapshot
///
///
///
/// In addition, an instance of the IVssWriterComponentsExt interface, which implements a requester-side version of the
/// IVssWriterComponents interface, is returned by IVssBackupComponents::GetWriterComponents.
///
/// IVssWriterComponents defines the following methods.
///
///
/// Method
/// Description
///
/// -
/// GetComponent
/// Returns the components belonging to a given writer instance.
///
/// -
/// GetComponentCount
/// Returns the number of components belonging to a given writer instance.
///
/// -
/// GetWriterInfo
/// Returns the instance and class identifier of the writer responsible for the components.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswritercomponents
[PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWriterComponents")]
public interface IVssWriterComponents
{
///
/// The GetComponent method returns an IVssComponent interface to one of a given writer's components explicitly stored in the
/// Backup Components Document.
///
/// List of IVssComponent objects that contain component information.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswritercomponents-getcomponent HRESULT GetComponent(
// [in] UINT iComponent, [out] IVssComponent **ppComponent );
IReadOnlyList Components { get; }
/// The GetWriterInfo method gets the instance and class identifier of the writer responsible for the components.
/// Identifier of the writer instance.
/// Identifier of the writer class.
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswritercomponents-getwriterinfo HRESULT GetWriterInfo(
// [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter );
void GetWriterInfo(out Guid pidInstance, out Guid pidWriter);
}
///
///
/// The GetDifferencedFile method returns information about a file set (a specified file or files) to participate in an
/// incremental or differential backup or restore as a differenced file—that is, backup and restores associated with it are to be
/// implemented as if entire files are copied to and from backup media (as opposed to using partial files).
///
/// This method can be called by a requester or a writer during backup or restore operations.
///
///
/// GetDifferencedFile can be called by a requester or a writer during backup or restore operations.
///
/// If the call to GetDifferencedFile is successful, the caller is responsible for freeing the string that is returned in the
/// pbstrPath and pbstrFilespec parameters by calling the SysFreeString function.
///
///
/// As writers can indicate differenced files with calls to IVssComponent::AddDifferencedFilesByLastModifyTime at any time prior to the
/// actual backing up of files, typically while handling a PostSnapshot event (CVssWriter::OnPostSnapshot), during backups
/// GetDifferencedFile is not usefully called prior to the return of IVssBackupComponents::DoSnapshotSet has successfully returned.
///
///
/// The time stamp returned by GetDifferencedFile applies to all files that match the returned path (pbstrPath) and file
/// specification (pbstrFilespec).
///
///
/// If the time-stamp value returned by GetDifferencedFile (pftLastModifyTime) is nonzero, a requester must respect this value
/// regardless of its own records and file system information and use it to determine whether the differenced file should be included in
/// a differential or incremental backup.
///
///
/// If the time stamp returned by GetDifferencedFile is zero, the requester can use file system information and its own records
/// to determine whether the differenced files should be included in a differential or incremental backup.
///
/// Differenced files can be either of the following:
///
/// -
///
/// Members of the current component or, if the component defines a component set, members of its subcomponents that were added to the
/// component using IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles
///
///
/// -
/// New files added to the component by IVssComponent::AddDifferencedFilesByLastModifyTime
///
///
///
/// When referring to a file set that is already part of the component, the combination of path, file specification, and recursion flag
/// (wszPath, wszFileSpec, and bRecursive, respectively) used when calling GetDifferencedFile should match that of a file set
/// already in the component, or one of its subcomponents (if the component defines a component set).
///
///
/// When GetDifferencedFile returns a differenced new file, that file's path (pbstrPath) should match or be beneath a path
/// already in the component, or one of its subcomponents (if the component defines a component set).
///
/// In addition, the files returned by GetDifferencedFile should not already be managed by component or writer.
/// If any of these criteria are violated, they constitute an error on the part of the writer and should be reported.
///
/// There is no method in the IVssComponent interface that allows for changing or adding an alternate location mapping for new files
/// returned by GetDifferencedFilesByLastModifyTime. If an alternate location mapping corresponds to the new file, then that
/// alternate location will be used.
///
///
public struct VssDifferencedFile
{
///
/// String containing the file specification of the files to be mapped.
///
/// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.
///
///
public string FileSpec;
///
/// The writer specification of the time of last modification for the difference files.
/// The last-modify time is always given in Greenwich Mean Time.
///
public DateTime LastModifyTime;
///
/// String containing the name of the directory or directory hierarchy containing the files to be mapped.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.
///
///
public string Path;
///
///
/// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it
/// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is
/// treated as a hierarchy of directories to be traversed recursively, or false if not.
///
/// For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points.
///
public bool Recursive;
}
///
///
/// The AddDirectedTarget method allows a writer to indicate at restore time that when a file is to be restored, it (the source
/// file) should be remapped. The file can be restored to a new restore location and/or ranges of its data restored to different offsets
/// within the restore location.
///
/// This method can be called by a writer only during a restore operation.
///
/// This method cannot be called while handling a BackupComplete (CVssWriter::OnBackupComplete) or BackupShutdown
/// (CVssWriter::OnBackupShutdown) event.
///
///
///
/// Only a writer can call AddDirectedTarget, and only during restore operations.
///
/// A requester will use the directed target information stored in the Backup Components Document only if the restore target is VSS_RT_DIRECTED.
///
///
/// The AddDirectedTarget method can be applied to any file managed in the current component or, if the component defines a
/// component set, in any of its nonselectable subcomponents.
///
///
/// Source and destination file specifications may point to the same file. This would allow remapping of a file into itself at restore time.
///
///
/// The syntax of the range listing (wszSourceRanges and wszDestinationRanges) is that of a comma-separated list of the form
/// offset1:length1, offset2:length2, where each offset and length is a 64-bit integer specifying a byte offset and length in
/// bytes, respectively. The offset and length can be expressed either as hexadecimal or decimal values.
///
/// The number of entries and their sizes must match in the source and destination range arguments.
///
/// AddDirectedTarget can use as its source file any file already managed by the component or one of its subcomponents if the
/// component defines a component set.
///
///
/// Partial files may be added as directed targets, if the partial file ranges to be backed up match the directed target source ranges
/// (see IVssComponent::AddPartialFile). This will allow you to remap partial files at restore time.
///
///
/// In this case, the requester retrieves the directed target information by calling the IVssComponent::GetDirectedTarget method and
/// uses that to implement the remapping of the backed-up data during restore.
///
///
public struct VssDirectedTarget
{
///
/// String containing the name of the file to which source file data will be remapped at restore time. The name of the file
/// (wszDestinationFilename) cannot contain wildcard characters (* or ?).
///
public string DestinationFilename;
/// String containing the path to which source file data will be remapped at restore time.
public string DestinationPath;
///
///
/// A null-terminated wide character string containing a comma-separated list of file offsets and lengths indicating the destination
/// file support range (locations to which the sections of the source file are to be restored).
///
/// The number and length of the destination file support ranges must match the number and size of source file support ranges.
///
public string DestinationRangeList;
///
/// String containing the name of the file (at backup time) that will be remapped at restore time (the source file). The name of the
/// file (wszSourceFilename) cannot contain wildcard characters (* or ?) and must be consistent with the file specification of a
/// file set containing the source path (wszSourcePath).
///
public string SourceFilename;
///
/// String containing the path to the directory at restore time containing the file to be restored (the source file). This path
/// should match or be beneath the path of a file set already in the component (or one of its subcomponents if the component defines
/// a component set).
///
public string SourcePath;
///
///
/// A null-terminated wide character string containing a comma-separated list of file offsets and lengths indicating the source file
/// support range (the sections of the file to actually be restored).
///
/// The number and length of the source file support ranges must match the number and size of destination file support ranges.
///
public string SourceRangeList;
}
///
///
/// The AddPartialFile method indicates that only portions of a given file are to be backed up and which portions those are.
///
/// Only a writer can call this method, and only during a backup operation.
///
///
/// Only a writer can call this method, and the writer cannot call this method during a restore operation.
///
/// The syntax of the range listing (wszRanges) is that of a comma-separated list of the form offset1:length1, offset2:length2,
/// where each offset and length is a 64-bit integer specifying a byte offset and length in bytes, respectively. The offset and length
/// can be expressed either as hexadecimal or decimal values.
///
///
/// If wszRange refers to a file containing all the offsets and lengths (a ranges file), wszRange will contain only the full path to the file.
///
/// A ranges file must be a binary file with the following format:
///
/// -
/// A 64-bit integer indicating the number of distinct file ranges that need to be backed up
///
/// -
///
/// Each range expressed as a pair of 64-bit integers: the offset into the file being backed up in bytes, and the length of data
/// starting from that offset to be backed up
///
///
///
/// In either case, a range indicates a subsection of a given file that is to be backed up, independent of the rest of the file.
///
/// Requesters can retrieve the partial file information using IVssComponent::GetPartialFile and use the offset and length information
/// returned by GetPartialFile to restore backed-up sections to the appropriate location within the copy of the file on disk at
/// restore time.
///
///
/// AddPartialFile can be applied to a file already managed by the component (or one of its subcomponents if the component
/// defines a component set), or it can add a new file to the component and indicate that it will participate in partial file operations.
///
///
/// When indicating that the file to participate is a new file, that file must exist on a shadow-copied volume and its path (wszPath)
/// should match or be beneath a path already in the component (or one of its subcomponents if the component defines a component set).
/// However, the file's file specification (wszFileSpec) should not match one in the components.
///
/// Any newly added files will not support alternate location mappings.
///
public struct VssPartialFile
{
///
/// String containing the name of the file involved in partial file operations. The name of the file (wszFilename) cannot contain
/// wildcard characters (* or ?) and must be consistent with the file specification of a file set containing the source path (wszPath).
///
public string Filename;
///
///
/// String containing any additional metadata required by a writer to validate a partial file restore operation. The information in
/// this metadata string will be opaque to requesters.
///
/// If additional metadata is not required, this value can be NULL.
///
public string? Metadata;
///
/// String containing the path of the file involved in partial file operations.
/// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters.
///
/// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.
///
///
/// This path should match or be beneath the path of a file set already in the component (or one of its subcomponents if the
/// component defines a component set).
///
///
public string Path;
///
///
/// String containing either a listing of file offsets and lengths that make up the partial file support range (the sections of the
/// file to actually be backed up), or the name of a file containing such a list.
///
/// Specifying the partial file support range is required, and this value cannot be NULL.
///
public string? Ranges;
}
///
/// The GetRestoreSubcomponent method returns the specified subcomponent associated with a given component.
/// Either a writer or a requester can call this method.
///
/// The caller should free the memory held by the pbstrLogicalPath and pbstrComponentName parameters by calling SysFreeString.
public struct VssRestoreSubcomponent
{
/// Pointer to a string containing the name of the subcomponent. The string cannot be empty.
public string ComponentName;
///
/// Pointer to a string containing the logical path of the subcomponent. The logical path cannot be empty when working with subcomponents.
///
public string LogicalPath;
/// Reserved for future use.
public bool Repair;
}