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; }