using System; using System.Collections.Generic; using System.Runtime.InteropServices; namespace Vanara.PInvoke.VssApi { ///

/// /// The IVssBackupComponents interface is used by a requester to poll writers about file status and to run backup/restore operations. /// /// Applications obtain an instance of the IVssBackupComponents interface by calling CreateVssBackupComponents. /// An IVssBackupComponents object can be used for only a single backup, restore, or Query operation. /// /// An IVssBackupComponents object must not be reused. For example, you cannot perform a backup or restore operation with the /// same IVssBackupComponents object that you have already used for a Query operation. /// ///

// https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssbackupcomponents [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssBackupComponents")] public interface IVssBackupComponents { ///

/// The GetWriterComponents method is used to return information about those components that have been stored in a /// requester's Backup Components Document. ///

/// A list of IVssWriterComponentsExt interface objects with the returned component information. /// /// /// WriterComponents retrieves component information for components stored in the Backup Components Document by earlier calls /// to IVssBackupComponents::AddComponent. /// /// /// The information in the components stored in the Backup Components Document is not static. If a writer updates a component during /// a restore, that change will be reflected in the component retrieved by GetWriterComponents. This is in contrast with /// component information found in the IVssWMComponent object returned by IVssExamineWriterMetadata::GetComponent. That information /// is read-only and comes from the Writer Metadata Document of a writer process. /// /// /// The IVssWriterComponentsExt interface pointer that is returned in the pWriterComponents parameter should not be cached, because /// the following IVssBackupComponents methods cause the interface pointer that is returned by GetWriterComponents to be no /// longer valid: /// /// /// IVssBackupComponents::PrepareForBackup IVssBackupComponents::DoSnapshotSet IVssBackupComponents::BackupComplete /// IVssBackupComponents::PreRestore IVssBackupComponents::PostRestore If you call one of these methods after you have retrieved an /// IVssWriterComponentsExt interface pointer by calling GetWriterComponents, you cannot reuse that pointer, because it is no /// longer valid. Instead, you must call GetWriterComponents again to retrieve a new IVssWriterComponentsExt interface pointer. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwritercomponents HRESULT // GetWriterComponents( [in] UINT iWriter, [out] IVssWriterComponentsExt **ppWriter ); IReadOnlyList WriterComponents { get; } ///

The WriterMetadata property returns the metadata for writers running on the system.

/// A list of IVssExamineWriterMetadata objects that contains the returned metadata. /// /// /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterMetadata and wait for it to complete prior to /// calling WriterMetadata. /// /// /// Although IVssBackupComponents::GatherWriterMetadata must be called prior to either a restore or backup operation, /// WriterMetadata is not typically called for restores. /// /// /// Component information retrieved (during backup operations) using IVssExamineWriterMetadata::GetComponent, where the /// IVssExamineWriterMetadata interface has been returned by GetWriterMetadata, comes from the Writer Metadata Document of a /// live writer process. /// /// /// This is in contrast to the information returned by GetWriterComponents (during restore operations), which was stored in the /// Backup Components Document by calls to AddComponent. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwritermetadata HRESULT // GetWriterMetadata( [in] UINT iWriter, [out] VSS_ID *pidInstance, [out] IVssExamineWriterMetadata **ppMetadata ); IReadOnlyList WriterMetadata { get; } ///

The WriterStatus property returns the status of the writers.

/// /// /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterStatus and wait for it to complete prior to /// calling WriterStatus. /// /// /// The VSS_E_WRITERERROR_XXX values returned in the pHrResultFailure parameter are generated by writers. /// VSS_E_WRITER_NOT_RESPONDING and VSS_E_WRITER_STATUS_NOT_AVAILABLE are generated by VSS. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwriterstatus HRESULT // GetWriterStatus( [in] UINT iWriter, [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter, [out] BSTR *pbstrWriter, [out] // VSS_WRITER_STATE *pnStatus, [out] HRESULT *phResultFailure ); IReadOnlyList WriterStatus { get; } ///

/// The AbortBackup method notifies VSS that a backup operation was terminated. /// /// This method must be called if a backup operation terminates after the creation of a shadow copy set with /// IVssBackupComponents::StartSnapshotSet and before IVssBackupComponents::DoSnapshotSet returns. /// /// If AbortBackup is called and no shadow copy or backup operations are underway, it is ignored. ///

/// /// AbortBackup generates an Abort event, which is handled by each instance of each writer through the CVssWriter::OnAbort method. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-abortbackup HRESULT AbortBackup(); void AbortBackup(); ///

/// The AddAlternativeLocationMapping method is used by a requester to indicate that an alternate location mapping was used /// to restore all the members of a file set in a given component. ///

/// Globally unique identifier (GUID) of the writer class that exported the component. /// /// Type of the component. The possible values of this parameter are defined by the VSS_COMPONENT_TYPE enumeration. /// /// /// String containing the logical path to the component. /// For more information, see Logical Pathing of Components. /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the component name. /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// /// String containing the path to the directory that originally contained the file to be relocated. This path can be local to 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. 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. /// /// /// /// String containing the original file specification. /// /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. /// /// /// /// /// A Boolean value that indicates 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 name of the directory where the file will be relocated. This path can be local to 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. /// /// /// The writerId, componentType, wszLogicalPath, and wszComponentName parameters identify a particular component, and the wszPath, /// wszFilespec, and bRecursive parameters identify the file set belonging to that component. /// /// /// The combination of path, file specification, and recursion flag (wszPath, wszFilespec, and bRecursive, respectively) provided to /// AddAlternativeLocationMapping to be mapped must match that of one of the file sets added to a component using either /// IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles. /// /// /// Because AddAlternativeLocationMapping is used to notify a writer that an alternate location was used to restore all the /// files in a component, it should not be called for any component or files in a component that have not had an alternate location /// mapping specified. /// /// /// The value of wszPath will have been mapped to wszDestination on restore; however, file names and subdirectories under the /// original path retain their same names. /// /// A typical usage of AddAlternativeLocationMapping during restore might be the following: /// /// /// Retrieve stored Writer Metadata Documents from the backup media and load that information with IVssExamineWriterMetadata::LoadFromXML. /// /// /// /// Call IVssExamineWriterMetadata::GetAlternateLocationMapping to get an IVssWMFiledesc interface with the mapping information and /// use IVssWMFiledesc::GetAlternateLocation to get the alternate location. /// /// /// /// /// Examine filedesc information to heuristically determine which component this alternate location mapping should be applied to. /// /// /// /// Call IVssBackupComponents::AddAlternativeLocationMapping to communicate where files were 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, if no valid alternate location mapping is defined this constitutes a writer error. /// A file may 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. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addalternativelocationmapping // HRESULT AddAlternativeLocationMapping( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE componentType, [in] LPCWSTR wszLogicalPath, // [in] LPCWSTR wszComponentName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive, [in] LPCWSTR wszDestination ); void AddAlternativeLocationMapping(Guid writerId, VSS_COMPONENT_TYPE componentType, [Optional] string wszLogicalPath, string wszComponentName, string wszPath, string wszFilespec, bool bRecursive, string wszDestination); ///

/// The AddComponent method is used to explicitly add to the backup set in the Backup Components Document all required /// components (nonselectable for backup components without a selectable for backup ancestor), and such optional (selectable for /// backup) components as the requester considers necessary. Members of component sets (components with a selectable for backup /// ancestor) are implicitly included in the backup set, but are not explicitly added to the Backup Components Document. ///

/// Identifies a specific instance of a writer. /// Writer class identifier. /// /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for permitted input values. /// /// /// /// String containing the logical path of the selectable for backup component. For more information, see Logical Pathing of Components. /// /// A logical path is not required when adding a component. Therefore, the value of this parameter can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the selectable for backup component. /// The value of this parameter cannot be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// The AddComponent method has meaning only if the backup operation takes place in component mode. /// Only these kinds of components should be added to the Backup Components Document using AddComponent. /// /// /// Components that are selectable for backup (see selectability for backup). /// /// /// Nonselectable-for-backup components with no selectable-for-backup ancestors. /// /// /// /// Nonselectable for backup components that have a selectable for backup ancestor in the hierarchy of their logical paths are part /// of a component set defined by the selectable for backup ancestor. These components are implicitly added to the Backup Components /// Document when the ancestor is added and should never be explicitly added to a requester's Backup Components Document by using /// AddComponent.The result of doing so is undefined (see Working with Selectability and Logical Paths). /// /// /// Selectable for backup components with selectable for backup ancestors are also subcomponents in a component set. They can be /// implicitly selected if their ancestor is selected (in which case they are not added to the Backup Components Document using /// AddComponent), or they can be explicitly selected using AddComponent. /// /// /// 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. /// /// /// The distinction between the instanceId and the writerID is necessary because it is possible to run multiple copies for the same writer. /// /// A writer's class identifier and instance can be found by calling IVssExamineWriterMetadata::GetIdentity. /// /// Before it calls AddComponent, a requester must have been initialized for backup by calling /// IVssBackupComponents::InitializeForBackup and IVssBackupComponents::GatherWriterMetadata. See Overview of Backup Initialization. /// /// /// The requester must call AddComponent to add the required components to the shadow copy before calling /// IVssBackupComponents::DoSnapshotSet to create the shadow copy. See Overview of the Backup Discovery Phase and Overview of /// Pre-Backup Tasks. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addcomponent HRESULT AddComponent( // [in] VSS_ID instanceId, [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR // wszComponentName ); void AddComponent(Guid instanceId, Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName); ///

/// The AddNewTarget method is used by a requester during a restore operation to indicate that the backup application plans /// to restore files to a new location. ///

/// /// Globally unique identifier (GUID) of the writer class containing the files that are to receive a new target. /// /// /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for possible return values. /// /// /// /// String containing the logical path of the component containing the files that are to receive a new restore target. For more /// information, see Logical Pathing of Components. /// /// /// The value of the string containing the logical path used here should be the same as was used when the component was added to the /// backup set using IVssBackupComponents::AddComponent. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the component containing the files that are to receive a new restore target. /// /// The string should not be and should contain the same component name as was used when the component was /// added to the backup set using IVssBackupComponents::AddComponent. /// /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the directory or directory hierarchy containing the files to receive a new restore target. /// 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. 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. /// /// /// /// String containing the file specification of the files to receive a new restore target. /// /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. /// /// /// /// /// Boolean indicating whether only the files in the directory defined by wszPath and matching the file specification provided by /// wszFileName are to receive a new restore target, or if all files in the hierarchy defined by wszPath and matching the file /// specification provided by wszFileName are to receive a new restore target. /// /// For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points. /// /// /// String containing the fully qualified path of the new restore target directory. /// 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. /// /// /// The component name specified as an argument to AddNewTarget (wszComponentName) must match a component that has already /// been added to the Backup Components Document. /// /// Therefore, wszComponentName can be the name of any component explicitly included in the Backup Components Document. /// /// Adding a new target for file in a subcomponent must be done using the name of the component that defines the component set /// containing the subcomponent. /// /// /// When specifying a file or files to have their restore target changed, a requester must ensure that the combination of path, file /// specification, and recursion flag (wszPath, wszFileSpec, and bRecursive, respectively) provided to AddNewTarget must /// match that of one of the file sets added to a component using IVssCreateWriterMetadata::AddFilesToFileGroup, /// IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles. /// /// /// When a requester calls AddNewTarget, it must do so before calling IVssBackupComponents::PreRestore. For more information, /// see Overview of Preparing for Restore. /// /// /// Path and file descriptor information can be obtained from the Writer Metadata Document by using the IVssWMFiledesc object /// returned by IVssWMComponent::GetFile, IVssWMComponent::GetDatabaseFile, or IVssWMComponent::GetDatabaseLogFile. The /// IVssWMComponent object is obtained from Writer Metadata Document by the IVssExamineWriterMetadata::GetComponent method. /// /// /// Writers can determine if files have been restored to new locations by using the IVssComponent::GetNewTargetCount and /// IVssComponent::GetNewTarget methods. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addnewtarget HRESULT AddNewTarget( // [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, [in] LPCWSTR // wszPath, [in] LPCWSTR wszFileName, [in] bool bRecursive, [in] LPCWSTR wszAlternatePath ); void AddNewTarget(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, string wszPath, string wszFileName, bool bRecursive, string wszAlternatePath); ///

/// The AddRestoreSubcomponent method indicates that a subcomponent member of a component set, which had been marked as /// nonselectable for backup but is marked selectable for restore, is to be restored irrespective of whether any other member of the /// component set will be restored. ///

/// Writer class identifier. /// /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for possible return values. /// /// /// /// String containing the logical path of the component in the backup document that defines the backup component set containing the /// subcomponent to be added for restore. /// /// The value of this parameter can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// /// String containing the logical path of the component in the backup document that defines the backup component set containing the /// subcomponent to be added for restore. /// /// The value of this parameter cannot be . /// There are no restrictions on the characters that can appear in a non- component name. /// /// /// String containing the logical path of the subcomponent to be added for restore. /// A logical path is required when adding a subcomponent. Therefore, the value of this parameter cannot be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the logical name of the subcomponent to be added for restore. /// The value of this parameter cannot be . /// There are no restrictions on the characters that can appear in a non- component name. /// /// This parameter is reserved for future use. This parameter should always be set to false /// /// /// Before calling AddRestoreSubcomponent, the root component defined by the wszLogicalPath and wszComponentName parameters /// must first be selected for restore using IVssBackupComponents::SetSelectedForRestore. /// /// If a requester is to support restoring subcomponents, this method must be called before IVssBackupComponents::PreRestore. /// /// AddRestoreSubcomponent is intended for the case in which all the files in a writer's component set must be backed up as a /// unit, but where it is desirable that selected files (subcomponents) be capable of being restored individually. /// /// /// To participate in such a restore, a subcomponent must have the bSelectableForRestore member of VSS_COMPONENTINFO set to /// TRUE. The component defined by the wszLogicalPath and wszComponentName parameters must also be selected for restore using IVssBackupComponents::SetSelectedForRestore. /// /// See Working with Selectability for Restore and Subcomponents for more information. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addrestoresubcomponent HRESULT // AddRestoreSubcomponent( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE componentType, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR // wszComponentName, [in] LPCWSTR wszSubComponentLogicalPath, [in] LPCWSTR wszSubComponentName, [in] bool bRepair ); void AddRestoreSubcomponent(Guid writerId, VSS_COMPONENT_TYPE componentType, [Optional] string wszLogicalPath, string wszComponentName, string wszSubComponentLogicalPath, string wszSubComponentName, bool bRepair); ///

/// Specifies the volumes to be included in a LUN resynchronization operation. This method is supported only on Windows server /// operating systems. ///

/// /// The identifier of the shadow copy that was returned by the IVssBackupComponents::AddToSnapshotSet method during backup. This /// parameter is required and cannot be Guid.Null. /// /// This parameter is reserved and must be zero. /// /// This parameter is optional and can be . A value of means that the contents of the /// shadow copy volume are to be copied back to the original volume. VSS identifies the original volume by the VDS_LUN_INFO /// information in the Backup Components Document. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-addsnapshottorecoveryset HRESULT // AddSnapshotToRecoverySet( [in] VSS_ID snapshotId, [in] DWORD dwFlags, [in, optional] VSS_PWSZ pwszDestinationVolume ); void AddSnapshotToRecoverySet(Guid snapshotId, [Optional] uint dwFlags, string pwszDestinationVolume = default); ///

The AddToSnapshotSet method adds an original volume or original remote file share to the shadow copy set.

/// /// /// String containing the name of the volume or the UNC path of the remote file share to be shadow copied. The name or UNC path must /// be in one of the following formats and must include a trailing backslash (\): /// /// /// /// The path of a mounted folder, for example, Y:\MountX\ /// /// /// A drive letter, for example, D:\ /// /// /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) /// /// /// A UNC path that specifies a remote file share, for example, \\Clusterx\Share1\ /// /// /// /// The provider to be used. Guid.Null can be used, in which case the default provider will be used. /// Returned identifier of the added shadow copy. /// /// /// 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. /// /// /// If pwszVolumeName is a UNC share path, the server name portion must be in hostname or fully qualified domain name format. UNC /// share names with IP addresses must be normalized by calling the IVssBackupComponentsEx4::GetRootAndLogicalPrefixPaths method /// before they are passed to AddToSnapshotSet. /// /// The maximum number of shadow copied volumes in a single shadow copy set is 64. /// If ProviderId is Guid.Null, the default provider is selected according to the following algorithm: /// /// /// If any hardware provider supports the given volume or remote file share, that provider is selected. /// /// /// If there is no hardware provider available, if any software provider supports the given volume, it is selected. /// /// /// /// If there is no hardware provider or software provider available, the system provider is selected. (There is only one /// preinstalled system provider, which must support all nonremovable local volumes.) /// /// /// /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. /// /// The shadow copy identifier that is returned in the pidSnapshot parameter is stored in the Backup Components Document. However, /// there is no method for querying this information, and the caller may need to store it so that it can be used during restore. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addtosnapshotset HRESULT // AddToSnapshotSet( [in] VSS_PWSZ pwszVolumeName, [in] VSS_ID ProviderId, [out] VSS_ID *pidSnapshot ); Guid AddToSnapshotSet(string pwszVolumeName, Guid ProviderId); ///

/// The BackupComplete method causes VSS to generate a BackupComplete event, which signals writers that the backup /// process has completed. ///

/// An IVssAsync instance. /// /// /// When working in component mode (IVssBackupComponents::SetBackupState was called with a select components argument of /// TRUE), writers can determine the success or failure of the backup of any component explicitly included in the Backup /// Components Document components by using IVssComponent::GetBackupSucceeded. Therefore, a well-behaved backup application /// (requester) must call IVssBackupComponents::SetBackupSucceeded after each component has been processed and prior to calling BackupComplete. /// /// /// Do not call this method if the call to IVssBackupComponents::DoSnapshotSet failed. For more information about how requesters use /// DoSnapshotSet, SetBackupSucceeded, and BackupComplete in a backup operation, see Overview of Pre-Backup Tasks and /// Overview of Actual Backup Of Files. /// /// /// This operation is asynchronous. The caller can use the QueryStatus interface method in the returned IVssAsync interface to /// determine the status of the notification. /// /// /// After calling BackupComplete, requesters must call GatherWriterStatus to cause the writer session to be set to a /// completed state. /// /// Note This is only necessary on Windows Server 2008 with Service Pack 2 (SP2) and earlier. /// The backup application can choose to abort the backup at any time after the shadow copy is created by calling IVssAsync::Cancel. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-backupcomplete HRESULT // BackupComplete( [out] IVssAsync **ppAsync ); IVssAsync BackupComplete(); ///

The BreakSnapshotSet method causes the existence of a shadow copy set to be "forgotten" by VSS.

/// Shadow copy set identifier. /// /// /// BreakSnapshotSet can be used only for shadow copies created by a hardware shadow copy provider. This method makes these /// shadow copies regular volumes. /// /// /// Shadow copies of volumes "broken" with BreakSnapshotSet must be managed independently of VSS as stand-alone volumes. See /// Breaking Shadow Copies for more information. /// /// /// IVssBackupComponentsEx2::BreakSnapshotSetEx is similar to the BreakSnapshotSet method, except that it has extra /// parameters to query status and specify how the shadow copy set is broken. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-breaksnapshotset HRESULT // BreakSnapshotSet( [in] VSS_ID SnapshotSetId ); void BreakSnapshotSet(Guid SnapshotSetId); ///

Breaks a shadow copy set according to requester-specified options.

/// A shadow copy set identifier. /// A bitmask of _VSS_HARDWARE_OPTIONS flags that specify how the shadow copy set is broken. /// /// A variable that receives an IVssAsync interface pointer that can be used to retrieve the status of the shadow copy set break /// operation. /// /// /// /// BreakSnapshotSetEx is similar to the IVssBackupComponents::BreakSnapshotSet method, except that it has extra parameters /// to query status and specify how the shadow copy set is broken. /// /// /// Like BreakSnapshotSet, BreakSnapshotSetEx can be used only for shadow copies that were created by a hardware shadow copy provider. /// /// /// After this method returns, the shadow copy volume is still a volume, but it is no longer a shadow copy. For more information, /// see Breaking Shadow Copies. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-breaksnapshotsetex HRESULT // BreakSnapshotSetEx( VSS_ID SnapshotSetID, DWORD dwBreakFlags, [out] IVssAsync **ppAsync ); IVssAsync BreakSnapshotSetEx(Guid SnapshotSetID, VSS_HARDWARE_OPTIONS dwBreakFlags); ///

The DeleteSnapshots method deletes one or more shadow copies or a shadow copy set.

/// Identifier of the shadow copy or a shadow copy set to be deleted. /// /// Type of the object on which all shadow copies will be deleted. The value of this parameter is VSS_OBJECT_SNAPSHOT or VSS_OBJECT_SNAPSHOT_SET. /// /// /// If the value of this parameter is TRUE, the provider will do everything possible to delete the shadow copy or shadow /// copies in a shadow copy set. If it is FALSE, no additional effort will be made. /// /// Number of deleted shadow copies. /// /// If an error occurs, the value of this parameter is the identifier of the first shadow copy that could not be deleted. Otherwise, /// it is Guid.Null. /// /// /// /// Multiple shadow copies in a shadow copy set are deleted sequentially. If an error occurs during one of these individual /// deletions, DeleteSnapshots will return immediately; no attempt will be made to delete any remaining shadow copies. The /// VSS_ID of the undeleted shadow copy is returned in pNondeletedSnapshotID. /// /// The requester is responsible for serializing the delete shadow copy operation. /// /// During a backup, shadow copies are automatically released as soon as the IVssBackupComponents instance is released. In this /// case, it is not necessary to explicitly delete shadow copies. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-deletesnapshots HRESULT // DeleteSnapshots( [in] VSS_ID SourceObjectId, [in] VSS_OBJECT_TYPE eSourceObjectType, [in] BOOL bForceDelete, [out] LONG // *plDeletedSnapshots, [out] VSS_ID *pNondeletedSnapshotID ); void DeleteSnapshots(Guid SourceObjectId, VSS_OBJECT_TYPE eSourceObjectType, bool bForceDelete, out int plDeletedSnapshots, out Guid pNondeletedSnapshotID); ///

The DisableWriterClasses method prevents a specific class of writers from receiving any events.

/// An array containing one or more writer class identifiers. /// /// /// If you have multiple running copies of the same writer, they will all have the same writer class identifier, but they will have /// different writer instance identifiers. Disabling a writer class causes all of the writer's instances to be disabled. /// /// /// If the DisableWriterClasses method and the IVssBackupComponents::EnableWriterClasses method are never called, all writer /// classes are enabled. /// /// /// After the first call to DisableWriterClasses returns, the writer classes that were specified in the rgWriterClassId array /// are disabled, and all other writer classes are enabled. /// /// /// If you call DisableWriterClasses more than once, each call adds the writers in the rgWriterClassId array to the list of /// disabled writers. /// /// /// If you call DisableWriterClasses one or more times and then call EnableWriterClasses, the first call to /// EnableWriterClasses cancels the effect of the calls to DisableWriterClasses and enables only the writers in the /// rgWriterClassId array. /// /// /// If you call DisableWriterClasses, you must do so before calling the IVssBackupComponents::GatherWriterMetadata method. If /// you call GatherWriterMetadata first and then call DisableWriterClasses, the call to DisableWriterClasses /// has no effect. If you need to call GatherWriterMetadata first, to determine which writer classes to disable, you must /// call it from a different instance of the IVssBackupComponents interface. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-disablewriterclasses HRESULT // DisableWriterClasses( [in] const VSS_ID *rgWriterClassId, [in] UINT cClassId ); void DisableWriterClasses([In] Guid[] rgWriterClassId); ///

The DisableWriterInstances method disables a specified writer instance or instances.

/// An array containing one or more writer instance identifiers. /// /// /// If you have multiple running copies of the same writer, they will all have the same writer class identifier, but they will have /// different writer instance identifiers. Disabling one instance of a writer does not cause the writer's other instances to be disabled. /// /// /// If you call DisableWriterInstances, you must do so before calling the IVssBackupComponents::GatherWriterMetadata method. /// If you call GatherWriterMetadata first and then call DisableWriterInstances, the call to /// DisableWriterInstances has no effect. If you need to call GatherWriterMetadata first, to determine which writer /// instances to disable, you must call it from a different instance of the IVssBackupComponents interface. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-disablewriterinstances HRESULT // DisableWriterInstances( [in] const VSS_ID *rgWriterInstanceId, [in] UINT cInstanceId ); void DisableWriterInstances([In] Guid[] rgWriterInstanceId); ///

Commits all shadow copies in this set simultaneously.

/// /// The required IVssAsync asynchronous interface. This is used to query the method execution state and /// to retrieve the final error code. /// /// /// The caller is responsible for releasing the IVssAsync interface. /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. /// /// For information on how to use IVssBackupComponents::DoSnapshotSet to create a standard backup shadow copy, see Overview /// of Pre-Backup Tasks and Simple Shadow Copy Creation for Backup. For information on how the method is used under different VSS /// contexts, see Implementation Details for Creating Shadow Copies. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-dosnapshotset HRESULT DoSnapshotSet( // [out] IVssAsync **ppAsync ); IVssAsync DoSnapshotSet(); ///

The EnableWriterClasses method enables the specified writers to receive all events.

/// An array containing one or more writer class identifiers. /// /// /// If the EnableWriterClasses method and the IVssBackupComponents::DisableWriterClasses method are never called, all writer /// classes are enabled. /// /// /// After the first call to EnableWriterClasses returns, the writer classes that were specified in the rgWriterClassId array /// are enabled, and all other writer classes are disabled. /// /// /// If you call EnableWriterClasses more than once, each call adds the writers in the rgWriterClassId array to the list of /// enabled writers. /// /// /// If you call EnableWriterClasses one or more times and then call DisableWriterClasses, the call to /// DisableWriterClasses disables any writers in the rgWriterClassId array that were enabled in the calls to EnableWriterClasses. /// /// /// If you call EnableWriterClasses, you must do so before calling the IVssBackupComponents::GatherWriterMetadata method. If /// you call GatherWriterMetadata first and then call EnableWriterClasses, the call to EnableWriterClasses has /// no effect. If you need to call GatherWriterMetadata first, to determine which writer classes to enable, you must call it /// from a different instance of the IVssBackupComponents interface. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-enablewriterclasses HRESULT // EnableWriterClasses( [in] const VSS_ID *rgWriterClassId, [in] UINT cClassId ); void EnableWriterClasses([In] Guid[] rgWriterClassId); ///

The ExposeSnapshot method exposes a shadow copy as a drive letter, mounted folder, or file share.

/// Shadow copy identifier. /// /// /// The path to the portion of the volume made available when exposing a shadow copy as a file share. The value of this parameter /// must be when exposing a shadow copy locally; that is, exposing it as a drive letter or mounted folder. /// /// The path cannot contain environment variables (for example, %MyEnv%) or wildcard characters. /// /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. /// /// /// /// Attributes of the exposed shadow copy indicating whether it is exposed locally or remotely. The value must be either the /// VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY or the VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY value of _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. /// /// /// When a shadow copy is exposed as a file share, the value of this parameter is the share name. If a shadow copy is exposed by /// mounting it as a device, the parameter value is a drive letter followed by a colon—for example, "X:" or a mounted folder path /// (for example, "Y:\MountX"). If the value of this parameter is , then VSS determines the share name or /// drive letter if the lAttributes parameter is VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY. /// /// /// The exposed name of the shadow copy. This is either a share name, a drive letter followed by a colon, or a mounted folder. The /// value is if ExposeSnapshot failed. VSS allocates the memory for this string. /// /// /// /// The caller is responsible for freeing the string that the pwszExposed parameter points to by calling the CoTaskMemFree function. /// /// When exposing a persistent shadow copy, it remains exposed through subsequent boots. /// /// When exposing a shadow copy of a volume, the shadow copy may be treated either as a mountable device or as a file system /// available for file sharing. /// /// /// When it is exposed as a device—as with other mountable devices—the shadow copy of a volume is exposed at its mount point (drive /// letter or mounted folder) starting with its root. /// /// When exposed as a file share, subsets (indicated by wszPathFromRoot) of the volume can be shared. /// For more information on how to expose shadow copies, see Exposing and Surfacing Shadow Copied Volumes. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-exposesnapshot HRESULT // ExposeSnapshot( [in] VSS_ID SnapshotId, [in] VSS_PWSZ wszPathFromRoot, [in] LONG lAttributes, [in] VSS_PWSZ wszExpose, [out] // VSS_PWSZ *pwszExposed ); string ExposeSnapshot(Guid SnapshotId, [Optional] string wszPathFromRoot, VSS_VOLUME_SNAPSHOT_ATTRIBUTES lAttributes, [Optional] string wszExpose); ///

/// Not supported. /// This method is reserved for future use. ///

/// This parameter is reserved for future use. /// This parameter is reserved for future use. /// This parameter is reserved for future use. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-fastrecovery HRESULT // FastRecovery( VSS_ID SnapshotSetID, DWORD dwFastRecoveryFlags, IVssAsync **ppAsync ); IVssAsync FastRecovery(Guid SnapshotSetID, [Optional] uint dwFastRecoveryFlags); ///

/// The FreeWriterMetadata method frees system resources allocated when IVssBackupComponents::GatherWriterMetadata was called. ///

/// /// /// This method should never be called prior to the completion of IVssBackupComponents::GatherWriterMetadata. The result of calling /// the method prior to completion of the metadata gather is undefined. /// /// /// Once writer metadata has been freed, it cannot be recovered by the current instance of the IVssBackupComponents interface. It /// will be necessary to create a new instance of IVssBackupComponents, and call the /// IVssBackupComponents::GatherWriterMetadata method again. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-freewritermetadata HRESULT FreeWriterMetadata(); void FreeWriterMetadata(); ///

The FreeWriterStatus method frees system resources allocated during the call to IVssBackupComponents::GatherWriterStatus.

// https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-freewriterstatus HRESULT FreeWriterStatus(); void FreeWriterStatus(); ///

/// The GatherWriterMetadata method prompts each writer to send the metadata they have collected. The method will generate an /// Identify event to communicate with writers. ///

/// An IVssAsync object containing the writer metadata. /// /// The caller is responsible for releasing the IVssAsync interface. /// GatherWriterMetadata should be called only once during the lifetime of a given IVssBackupComponents object. /// /// GatherWriterMetadata generates an Identify event, which is handled by each instance of each writer through the /// CVssWriter::OnIdentify method, which is used to fill the Writer Metadata Document. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-gatherwritermetadata HRESULT // GatherWriterMetadata( [out] IVssAsync **pAsync ); IVssAsync GatherWriterMetadata(); ///

The GatherWriterStatus method prompts each writer to send a status message.

/// An IVssAsync object containing the writer status data. /// /// The caller of this method should also call IVssBackupComponents::FreeWriterStatus after receiving the status of each writer. /// /// After calling BackupComplete, requesters must call GatherWriterStatus to cause the writer session to be set to a /// completed state. /// /// Note This is only necessary on Windows Server 2008 with Service Pack 2 (SP2) and earlier. /// The CVssWriter class handles the status message sent by each writer. /// The caller is responsible for releasing the IVssAsync interface. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-gatherwriterstatus HRESULT // GatherWriterStatus( [out] IVssAsync **pAsync ); IVssAsync GatherWriterStatus(); ///

/// Normalizes a local volume path or UNC share path so that it can be passed to the IVssBackupComponents::AddToSnapshotSet method. ///

/// The path to be normalized. /// Receives the root path that should be passed to the IVssBackupComponents::AddToSnapshotSet method. /// /// If pwszFilePath is a local path, this parameter receives the volume GUID name. If it's a UNC path, this parameter receives a /// fully evaluated share path. /// /// /// If pwszFilePath is a UNC share path, the server name portion can be /// /// /// A host name /// /// /// /// A fully qualified domain name /// /// /// /// An IP address /// /// /// /// /// This parameter specifies whether host name format or fully qualified domain name format should be used in the server name /// portion of the normalized root path that is returned in the ppwszRootPath parameter. /// /// If this parameter is FALSE, simple host name format will be used. /// The default value for this parameter is FALSE. /// If this parameter is TRUE, fully qualified domain name will be used. /// In a deployment where a host name could exist in multiple domain suffixes, this parameter should be TRUE. /// /// /// /// This method normalizes a local volume path or UNC share path and separates it into a root path and a logical prefix path. The /// root path can then be passed to the IVssBackupComponents::AddToSnapshotSet method. /// /// /// If pwszFilePath is a local volume path, the root path will be similar to a volume mount point. In this case, the root and the /// logical prefix paths map to the results of GetVolumePathName and GetVolumeNameForVolumeMountPoint, respectively. /// /// /// If pwszFilePath is a UNC share path, the root and logical prefix paths map to the root path of the file share and the fully /// evaluated physical share path (which will take into account DFS and cluster deployment), respectively. /// /// /// If you call this method more than once for the same shadow copy set creation operation, you must set the /// bNormalizeFQDNforRootPath to the same value for every call. Fully qualified domain name format and host name format cannot be /// mixed in the same shadow copy set. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex4-getrootandlogicalprefixpaths // HRESULT GetRootAndLogicalPrefixPaths( [in] VSS_PWSZ pwszFilePath, [out] VSS_PWSZ *ppwszRootPath, [out] VSS_PWSZ // *ppwszLogicalPrefix, [in, optional] BOOL bNormalizeFQDNforRootPath ); void GetRootAndLogicalPrefixPaths(string pwszFilePath, out string ppwszRootPath, out string ppwszLogicalPrefix, bool bNormalizeFQDNforRootPath = false); ///

Returns the requester's session identifier.

/// A variable that receives the session identifier. /// /// /// The session identifier is an opaque value that uniquely identifies a backup or restore session. It is used to distinguish the /// current session among multiple parallel backup or restore sessions. /// /// /// As a best practice, writers and requesters should include the session ID in all diagnostics messages used for event logging and tracing. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-getsessionid HRESULT // GetSessionId( [out] VSS_ID *idSession ); Guid GetSessionId(); ///

The GetSnapshotProperties method gets the properties of the specified shadow copy.

/// The identifier of the shadow copy of a volume as returned by IVssBackupComponents::AddToSnapshotSet. /// /// The address of a caller-allocated VSS_SNAPSHOT_PROP structure that receives the shadow copy properties. The software provider is /// responsible for setting the members of this structure. The software provider allocates memory for all string members that it /// sets in the structure. When the structure is no longer needed, the software provider is responsible for freeing these strings by /// calling the VssFreeSnapshotProperties function. /// /// /// /// The caller should set the contents of the VSS_SNAPSHOT_PROP structure to zero before calling the GetSnapshotProperties method. /// /// The provider is responsible for allocating and freeing the strings in the VSS_SNAPSHOT_PROP structure. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getsnapshotproperties HRESULT // GetSnapshotProperties( [in] VSS_ID SnapshotId, [out] VSS_SNAPSHOT_PROP *pProp ); VSS_SNAPSHOT_PROP GetSnapshotProperties(Guid SnapshotId); ///

The ImportSnapshots method imports shadow copies transported from a different machine.

/// An IVssAsync object containing the imported shadow copy status data. /// /// Only one shadow copy can be imported at a time. /// The requester is responsible for serializing the import shadow copy operation. /// The caller is responsible for releasing the IVssAsync interface. /// For more information on importing shadow copies, see Importing Transportable Shadow Copied Volumes. /// /// Transportable shadow copies in a cluster: For details about using transportable shadow copies in a cluster, see Fast /// Recovery Using Transportable Shadow Copied Volumes. The transportable shadow copy must be imported from outside the cluster as /// long as the original volume is mounted within the cluster. /// /// /// Note If the shadow copy import fails, the Volume Shadow Copy Service won't clean up LUNs on its own. The requester has to /// initiate the cleanup of LUNs. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-importsnapshots HRESULT // ImportSnapshots( [out] IVssAsync **ppAsync ); IVssAsync ImportSnapshots(); ///

The InitializeForBackup method initializes the backup components metadata in preparation for backup.

/// /// Optional. During imports of transported shadow copies, this parameter must be the original document generated when creating the /// saved shadow copy and saved using IVssBackupComponents::SaveAsXML. /// /// /// /// The XML document supplied to this method initializes the IVssBackupComponents object with metadata previously stored by a call /// to IVssBackupComponents::SaveAsXML. Users should not tamper with this metadata document. /// /// /// For more information on how to use InitializeForBackup with transportable shadow copies, see Importing Transportable /// Shadow Copied Volumes. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-initializeforbackup HRESULT // InitializeForBackup( [in] BSTR bstrXML ); void InitializeForBackup([Optional] string bstrXML); ///

/// The InitializeForRestore method initializes the IVssBackupComponents interface in preparation for a restore operation. ///

/// XML string containing the Backup Components Document generated by a backup operation and saved by IVssBackupComponents::SaveAsXML. /// /// The XML document supplied to this method initializes the IVssBackupComponents object with metadata previously stored by a call /// to IVssBackupComponents::SaveAsXML. Users should not tamper with this metadata document. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-initializeforrestore HRESULT // InitializeForRestore( [in] BSTR bstrXML ); void InitializeForRestore([Optional] string bstrXML); ///

/// The IsVolumeSupported method determines whether the specified provider supports shadow copies on the specified volume or /// remote file share. ///

/// /// Provider identifier. If the value is Guid.Null, IsVolumeSupported checks whether any provider supports the volume or /// remote file share. /// /// /// /// Volume name or UNC path of remote file share. The name or UNC path must be in one of the following formats and must include a /// trailing backslash (\): /// /// /// /// The path of a mounted folder, for example, Y:\MountX\ /// /// /// A drive letter, for example, D:\ /// /// /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) /// /// /// A UNC path that specifies a remote file share, for example, \\Clusterx\Share1\ /// /// /// /// /// Address of a caller-allocated variable that receives TRUE if shadow copies are supported on the specified volume or /// remote file share, or FALSE otherwise. /// /// /// /// 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. /// /// /// IsVolumeSupported will return TRUE if it is possible to create shadow copies on the given volume, even if the /// current configuration does not allow the creation of shadow copies on that volume at the present time. /// /// /// For example, if the maximum number of shadow copies has been reached on a given volume (and therefore no more shadow copies can /// be created on that volume), the method will still indicate that the volume can be shadow copied. /// /// /// Note For more information about the maximum number of shadow copies that can be created on a volume, see the entry for /// MaxShadowCopies in Registry Keys and Values for Backup and Restore. /// /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. /// bool IsVolumeSupported(Guid ProviderId, string pwszVolumeName); ///

/// The PostRestore method will cause VSS to generate a PostRestore event, signaling writers that the current restore /// operation has finished. ///

/// An IVssAsync object that contains status data for the signaled event. /// The caller is responsible for releasing the IVssAsync interface. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-postrestore HRESULT PostRestore( // [out] IVssAsync **ppAsync ); IVssAsync PostRestore(); ///

/// Not supported. /// This method is reserved for future use. ///

/// This parameter is reserved for future use. /// This parameter is reserved for future use. /// This parameter is reserved for future use. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-prefastrecovery HRESULT // PreFastRecovery( VSS_ID SnapshotSetID, DWORD dwPreFastRecoveryFlags, IVssAsync **ppAsync ); IVssAsync PreFastRecovery(Guid SnapshotSetID, [Optional] uint dwPreFastRecoveryFlags); ///

/// The PrepareForBackup method will cause VSS to generate a PrepareForBackup event, signaling writers to prepare for an /// upcoming backup operation. This makes a requester's Backup Components Document available to writers. ///

/// /// An instance of the IVssAsync interface that is used to determine when the asynchronous operation is complete. /// /// /// /// PrepareForBackup generates a PrepareForBackup event, which is handled by each instance of each writer through the /// CVssWriter::OnPrepareBackup method. /// /// Before PrepareForBackup can be called, IVssBackupComponents::SetBackupState must be called. /// /// The Backup Components Document can still be modified by writers in their PrepareForBackup event handler /// (CVssWriter::OnPrepareBackup), and afterward until the generation of a BackupComplete event. /// /// The caller is responsible for releasing the IVssAsync interface. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-prepareforbackup HRESULT // PrepareForBackup( [out] IVssAsync **ppAsync ); IVssAsync PrepareForBackup(); ///

/// The PreRestore method will cause VSS to generate a PreRestore event, signaling writers to prepare for an upcoming restore operation. ///

/// An IVssAsync object containing status data for the signaled event. /// /// The caller is responsible for releasing the IVssAsync interface pointer. /// /// Special consideration should be given to EFI systems when the requester has selected the Automated System Recovery (ASR) writer /// for restore. If you are restoring to a disk that contains the EFI partition, and one of the following conditions exists, you /// must first clean the disk by calling the IVdsAdvancedDisk::Clean method: /// /// /// /// You are restoring to an EFI system disk whose partitioning has changed since the last ASR backup. /// /// /// You are restoring to a different physical drive than the one from which the backup was taken. /// /// /// Failure to perform this disk-cleaning step may result in unexpected results during PreRestore. /// For more information about the ASR writer, see In-Box VSS Writers. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-prerestore HRESULT PreRestore( [out] // IVssAsync **ppAsync ); IVssAsync PreRestore(); ///

/// The Query method queries providers on the system and/or the completed shadow copies in the system that reside in the /// current context. The method can be called only during backup operations. ///

/// Reserved. The value of this parameter must be Guid.Null. /// /// /// Indicates restriction of the query to the given object type. A value of VSS_OBJECT_NONE indicates no restriction—that is, all /// objects will be queried. /// /// Currently, the value of this parameter must be VSS_OBJECT_NONE. /// /// /// Object types to be returned. The value of this parameter must be either VSS_OBJECT_SNAPSHOT or VSS_OBJECT_PROVIDER. /// /// An IVssEnumObject enumerator object. /// /// /// Because Query returns only information on completed shadow copies, the only shadow copy state it can disclose is VSS_SS_COMPLETED. /// /// /// The method may be called only during backup operations and must be preceded by calls to /// IVssBackupComponents::InitializeForBackup and IVssBackupComponents::SetContext. /// /// /// While Query can return information on all of the providers available on a system, it will return only information about /// shadow copies with the current context (set by IVssBackupComponents::SetContext). For instance, if the _VSS_SNAPSHOT_CONTEXT /// context is set to VSS_CTX_BACKUP, Query will not return information on a shadow copy created with a context of VSS_CTX_FILE_SHARE_BACKUP. /// /// /// While this method currently returns a lists of all available providers and/or all completed shadow copies, in the future, /// specialized queries may be supported: for instance, querying all shadow copies associated with a provider. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-query HRESULT Query( [in] VSS_ID // QueriedObjectId, [in] VSS_OBJECT_TYPE eQueriedObjectType, [in] VSS_OBJECT_TYPE eReturnedObjectsType, [out] IVssEnumObject // **ppEnum ); IVssEnumObject Query(Guid QueriedObjectId, VSS_OBJECT_TYPE eQueriedObjectType, VSS_OBJECT_TYPE eReturnedObjectsType); ///

/// The QueryRevertStatus method returns an IVssAsync interface pointer that can be used to determine the status of the /// revert operation. ///

/// /// /// String containing the name of the volume. The name must be in one of the following formats and must include a trailing backslash (\): /// /// /// /// The path of a mounted folder, for example, Y:\MountX\ /// /// /// A drive letter, for example, D:\ /// /// /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) /// /// /// /// An IVssAsync interface pointer that can be used to retrieve the status of the revert process. /// /// The revert operation will continue even if the computer is rebooted, and cannot be canceled or undone, except by restoring a /// backup created using another method. The QueryStatus method on the returned IVssAsync interface cannot return /// VSS_S_ASYNC_CANCELLED as the revert operation cannot be canceled after it has started. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-queryrevertstatus HRESULT // QueryRevertStatus( [in] VSS_PWSZ pwszVolume, [out] IVssAsync **ppAsync ); IVssAsync QueryRevertStatus(string pwszVolume); ///

Initiates a LUN resynchronization operation. This method is supported only on Windows server operating systems.

/// A bitmask of VSS_RECOVERY_OPTIONS flags that specify how the resynchronization is to be performed. /// /// A variable that receives an IVssAsync interface pointer that can be used to retrieve the status of the LUN resynchronization /// operation. /// /// /// /// At the end of the resynchronization operation, by default the newly resychronized LUN will have the same disk signature that the /// destination LUN had before the resynchronization. /// /// /// This method cannot be called in WinPE, and it cannot be called in Safe mode. Before calling this method, the caller must call /// IVssBackupComponents::InitializeForRestore to prepare for the resynchronization. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-recoverset HRESULT RecoverSet( // [in] DWORD dwFlags, [out] IVssAsync **ppAsync ); IVssAsync RecoverSet(VSS_RECOVERY_OPTIONS dwFlags); ///

/// /// The RevertToSnapshot method reverts a volume to a previous shadow copy. Only shadow copies created with persistent /// contexts ( VSS_CTX_APP_ROLLBACK, VSS_CTX_CLIENT_ACCESSIBLE, VSS_CTX_CLIENT_ACCESSIBLE_WRITERS, or /// VSS_CTX_NAS_ROLLBACK) are supported. /// /// Note This method is only supported on Windows Server operating systems. ///

/// VSS_ID of the shadow copy to revert. /// /// If this parameter is TRUE, the volume will be dismounted and reverted even if the volume is in use. /// /// /// This operation cannot be canceled, or undone once completed. If the computer is rebooted during the revert operation, the revert /// process will continue when the system is restarted. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-reverttosnapshot HRESULT // RevertToSnapshot( [in] VSS_ID SnapshotId, [in] BOOL bForceDismount ); void RevertToSnapshot(Guid SnapshotId, bool bForceDismount); ///

/// The SaveAsXML method saves the Backup Components Document containing a requester's state information to a specified /// string. This XML document, which contains the Backup Components Document, should always be securely saved as part of a backup operation. ///

/// The Backup Components Document containing a requester's state information. /// /// /// For a typical backup operation, SaveAsXML should not be called until after both writers and the requester are finished /// modifying the Backup Components Document. /// /// /// Writers can continue to modify the Backup Components Document until their successful return from handling the PostSnapshot event /// (CVssWriter::OnPostSnapshot), or equivalently upon the completion of IVssBackupComponents::DoSnapshotSet. /// /// /// Requesters will need to continue to modify the Backup Components Document as the backup progresses. In particular, a requester /// will store a component-by-component record of the success or failure of the backup through calls to the /// IVssBackupComponents::SetBackupSucceeded method. /// /// /// Once the requester has finished modifying the Backup Components Document, the requester should use SaveAsXML to save a /// copy of the document to the backup media. /// /// /// A Backup Components Document can be saved at earlier points in the life cycle of a backup operation—for instance, to support the /// generation of transportable shadow copies to be handled on remote machines. (See Importing Transportable Shadow Copied Volumes /// for more information.) /// /// /// However, SaveAsXML should never be called prior to IVssBackupComponents::PrepareForBackup, because the Backup Components /// Document will not have been filled by the requester and the writers. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-saveasxml HRESULT SaveAsXML( [in] // BSTR *pbstrXML ); string SaveAsXML(); ///

/// The SetAdditionalRestores method is used by a requester during incremental or differential restore operations to indicate /// to writers that a given component will require additional restore operations to completely retrieve it. ///

/// Writer identifier. /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. /// /// String containing the logical path of the component to be added. /// For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as was used when the component was added to the /// backup set using IVssBackupComponents::AddComponent. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the component. /// /// The value of the string should not be , and should contain the same component as was used when the /// component was added to the backup set using IVssBackupComponents::AddComponent. /// /// /// /// If the value of this parameter is true, additional restores of the component will follow this restore. If the value is /// false, additional restores of the component will not follow this restore. /// /// /// /// The information provided by the SetAdditionalRestores 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 SetAdditionalRestores for a component is set to true, this means that 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 on a component is set to false, then after the component is restored, the application /// can complete its recovery operation and be brought back online. /// /// This method must be called before IVssBackupComponents::PreRestore. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setadditionalrestores HRESULT // SetAdditionalRestores( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR // wszComponentName, [in] bool bAdditionalRestores ); void SetAdditionalRestores(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, bool bAdditionalRestores); ///

Marks the restore of a component as authoritative for a replicated data store.

/// The globally unique identifier (GUID) of the writer class. /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. /// /// A string containing the logical path of the component. For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as the string that was used when the component /// was added. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// A string containing the name of the component. /// /// The string cannot be and should contain the same component name as the string that was used when the /// component was added to the backup set using the IVssBackupComponents::AddComponent method. /// /// /// /// Set this variable to true to indicate that the restore of the component is authoritative, or false otherwise. /// The default value is false. /// /// /// The SetAuthoritativeRestore method can only be called during a restore operation. /// /// 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/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setauthoritativerestore HRESULT // SetAuthoritativeRestore( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR // wszComponentName, [in] bool bAuth ); void SetAuthoritativeRestore(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, bool bAuth); ///

The SetBackupOptions method sets a string of private, or writer-dependent, backup parameters for a component.

/// Writer identifier. /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. /// /// String containing the logical path of the component. /// For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as was used when the component was added to the /// backup set using IVssBackupComponents::AddComponent. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the component. /// /// The string containing the name cannot be and should contain the same component name as was used when the /// component was added to the backup set using IVssBackupComponents::AddComponent. /// /// /// String containing the backup parameters to be set. /// /// The following are the valid return codes for this method. /// /// /// Value /// Meaning /// /// /// S_OK /// Successfully set the backup options. /// /// /// E_INVALIDARG /// One of the parameter values is not valid. /// /// /// E_OUTOFMEMORY /// The caller is out of memory or other system resources. /// /// /// VSS_E_BAD_STATE /// /// The backup components object is not initialized, this method has been called during a restore operation, or this method has not /// been called within the correct sequence. /// /// /// /// VSS_E_OBJECT_NOT_FOUND /// The backup component does not exist. /// /// /// VSS_E_INVALID_XML_DOCUMENT /// /// The XML document is not valid. Check the event log for details. For more information, see Event and Error Handling Under VSS. /// /// /// /// VSS_E_UNEXPECTED /// /// Unexpected error. The error code is logged in the error log file. For more information, see Event and Error Handling Under VSS. /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported until Windows Server 2008 R2 /// and Windows 7. E_UNEXPECTED is used instead. /// /// /// /// /// /// /// The exact syntax and content of the backup options set by the wszBackupOptions parameter of the SetBackupOptions method /// will depend on the specific writer being contacted. /// /// This method must be called before IVssBackupComponents::PrepareForBackup. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupoptions HRESULT // SetBackupOptions( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, // [in] LPCWSTR wszBackupOptions ); void SetBackupOptions(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, string wszBackupOptions); ///

The SetBackupState method defines an overall configuration for a backup operation.

/// /// Indicates whether a backup or restore operation will be in component mode. /// /// Operation in component mode supports selectively backing up designated individual components (which can allow their exclusion), /// or only supports backing up all files and components on a volume. /// /// The Boolean is true if the operation will be conducted in component mode and false if not. /// /// Indicates whether a bootable system state backup is being performed. /// A VSS_BACKUP_TYPE enumeration value indicating the type of backup to be performed. /// /// Optional. If the value of this parameter is true, partial file support is enabled. The default value for this argument is false. /// /// Applications must call SetBackupState prior to calling IVssBackupComponents::PrepareForBackup. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupstate HRESULT // SetBackupState( [in] bool bSelectComponents, [in] bool bBackupBootableSystemState, [in] VSS_BACKUP_TYPE backupType, [in] bool // bPartialFileSupport ); void SetBackupState(bool bSelectComponents, bool bBackupBootableSystemState, VSS_BACKUP_TYPE backupType, bool bPartialFileSupport = false); ///

/// The SetBackupSucceeded method indicates whether the backup of the specified component of a specific writer was successful. ///

/// Globally unique identifier (GUID) of the writer instance. /// Globally unique identifier (GUID) of the writer class. /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. /// /// String containing the logical path of the component. /// For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as was used when the component was added to the /// backup set using IVssBackupComponents::AddComponent. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the component. /// /// The string cannot be and should contain the same component name as was used when the component was added /// to the backup set using IVssBackupComponents::AddComponent. /// /// /// Set this parameter to true if the component was successfully backed up, or false otherwise. /// /// /// When working in component mode (when IVssBackupComponents::SetBackupState is called with its select components argument set to /// true), writers check the state of each components backup using IVssComponent::GetBackupSucceeded. Therefore, a /// well-behaved backup application (requester) must call SetBackupSucceeded after each component has been processed and /// prior to calling IVssBackupComponents::BackupComplete. /// /// /// Do not call this method if the call to IVssBackupComponents::DoSnapshotSet failed. For more information about how requesters use /// DoSnapshotSet, SetBackupSucceeded, and BackupComplete in a backup operation, see Overview of Pre-Backup Tasks and /// Overview of Actual Backup Of Files. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupsucceeded HRESULT // SetBackupSucceeded( [in] VSS_ID instanceId, [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] // LPCWSTR wszComponentName, [in] bool bSucceded ); void SetBackupSucceeded(Guid instanceId, Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, bool bSucceded); ///

The SetContext method sets the context for subsequent shadow copy-related operations.

/// /// The context to be set. The context must be one of the supported values of _VSS_SNAPSHOT_CONTEXT or a supported bit mask (or /// bitwise OR) of _VSS_VOLUME_SNAPSHOT_ATTRIBUTES with a valid _VSS_SNAPSHOT_CONTEXT. /// /// /// The default context for VSS shadow copies is VSS_CTX_BACKUP. /// /// Windows XP: The only supported context is the default context, VSS_CTX_BACKUP. Therefore, calling SetContext under /// Windows XP returns E_NOTIMPL. /// /// SetContext can be called only once, and it must be called prior to calling most VSS functions. /// /// For details on how the context set by IVssBackupComponents::SetContext affects how a shadow copy is created and managed, /// see Implementation Details for Creating Shadow Copies. /// /// For a complete discussion of the permitted shadow copy contexts, see _VSS_SNAPSHOT_CONTEXT and _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setcontext HRESULT SetContext( [in] // LONG lContext ); void SetContext(VSS_SNAPSHOT_CONTEXT lContext); ///

The SetFileRestoreStatus method indicates whether some, all, or no files were successfully restored.

/// /// The SetPreviousBackupStamp method sets the backup stamp of an earlier backup operation, upon which a differential or /// incremental backup operation will be based. /// /// The method can be called only during a backup operation. ///

/// Writer identifier. /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. /// /// String containing the logical path of the component. /// For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as was used when the component was added to the /// backup set using IVssBackupComponents::AddComponent. /// /// The logical path can be . /// /// /// String containing the name of the component. /// /// The string cannot be and should contain the same component name as was used when the component was added /// to the backup set using IVssBackupComponents::AddComponent. /// /// /// The backup stamp to be set. /// /// This method should be called before IVssBackupComponents::PrepareForBackup. /// Only requesters can call this method. /// /// The backup stamp set by SetPreviousBackupStamp applies to all files in the component and any nonselectable subcomponents /// it has. /// /// /// Requesters merely store the backup stamps in the Backup Components Document. They cannot make direct use of the backup stamps, /// do not know their format, and do not know how to generate them. /// /// /// Therefore, the value set with SetPreviousBackupStamp should either be retrieved from the stored Backup Components /// Document of an earlier backup operation (using IVssComponent::GetBackupStamp for the correct component), or from information /// stored by the requester into its own internal records. /// /// /// A writer will then obtain this value (using IVssComponent::GetPreviousBackupStamp) and using it will be able to mark the /// appropriate files for participation in an incremental or differential backup. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setpreviousbackupstamp HRESULT // SetPreviousBackupStamp( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR // wszComponentName, [in] LPCWSTR wszPreviousBackupStamp ); void SetPreviousBackupStamp(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, string wszPreviousBackupStamp); ///

/// The SetRangesFilePath method is used when a partial file operation requires a ranges file, and that file has been /// restored to a location other than its original one. ///

/// /// Globally unique identifier (GUID) of the writer class containing the files involved in the partial file operation. /// /// Identifies the type of the component. Refer to VSS_COMPONENT_TYPE for possible return values. /// /// String containing the logical path of the component containing the files that are participating in the partial file operation. /// For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as was used when the component was added to the /// backup set using IVssBackupComponents::AddComponent. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the component containing the files that are participating in the partial file operation. /// /// The string cannot be and should contain the same component name as was used when the component was added /// to the backup set using IVssBackupComponents::AddComponent. /// /// /// /// Index number of the partial file. The value of this parameter is an integer from 0 to n–1 inclusive, where n is the total number /// of partial files associated with a given component. The value of n is returned by IVssComponent::GetPartialFileCount. /// /// String containing the fully qualified path of a ranges file. /// Calling SetRangesFilePath is not necessary if ranges files are restored in place. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrangesfilepath HRESULT // SetRangesFilePath( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, UINT iPartialFile, // LPCWSTR wszRangesFile ); void SetRangesFilePath(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, uint iPartialFile, string wszRangesFile); ///

Assigns a new logical name to a component that is being restored.

/// The globally unique identifier (GUID) of the writer class. /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. /// /// A string containing the logical path of the component. For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as the string that was used when the component /// was added. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// A string containing the name of the component. /// /// The string cannot be and should contain the same component name as was the component name that was used /// when the component was added to the backup set using the IVssBackupComponents::AddComponent method. /// /// /// A string containing the restore name to be set for the component. /// /// The SetRestoreName method can only be called during a restore operation. /// /// 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/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setrestorename HRESULT // SetRestoreName( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, LPCWSTR wszRestoreName ); void SetRestoreName(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, string wszRestoreName); ///

/// The SetRestoreOptions method sets a string of private, or writer-dependent, restore parameters for a writer component. ///

/// Writer identifier. /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. /// /// String containing the logical path of the component. For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as was used when the component was added to the /// backup set using IVssBackupComponents::AddComponent. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non-NULL logical path. /// /// /// String containing the name of the component. /// /// The string cannot be and should contain the same component name as was used when the component was added /// to the backup set using IVssBackupComponents::AddComponent. /// /// /// /// String containing the private string of restore parameters. For more information see Setting VSS Restore Options. /// /// /// This method must be called before IVssBackupComponents::PreRestore. /// /// The exact syntax and content of the restore options set by the wszRestoreOptions parameter of the SetRestoreOptions /// method will depend on the specific writer being contacted. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrestoreoptions HRESULT // SetRestoreOptions( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, // [in] LPCWSTR wszRestoreOptions ); void SetRestoreOptions(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, string wszRestoreOptions); ///

The SetRestoreState method defines an overall configuration for a restore operation.

/// A VSS_RESTORE_TYPE enumeration value indicating the type of restore to be performed. /// /// /// Typically, most restore operations will not need to override the default restore type (VSS_RTYPE_UNDEFINED). Writers should /// treat this restore type as if it were VSS_RTYPE_BY_COPY. /// /// If applications need to call SetRestoreState, it should be called prior to calling IVssBackupComponents::PreRestore. /// If SetRestoreState is not called prior to IVssBackupComponents::PreRestore, the default restore state () is used. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrestorestate HRESULT // SetRestoreState( [in] VSS_RESTORE_TYPE restoreType ); void SetRestoreState(VSS_RESTORE_TYPE restoreType); ///

/// Sets the roll-forward operation type for a component and specifies the restore point for a partial roll-forward operation. ///

/// The globally unique identifier (GUID) of the writer class. /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. /// /// A string containing the logical path of the component. For more information, see Logical Pathing of Components. /// /// The value of the string containing the logical path used here should be the same as the string that was used when the component /// was added. /// /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// A string containing the name of the component. /// /// The string cannot be and should contain the same component name as the string that was used when the /// component was added to the backup set using the IVssBackupComponents::AddComponent method. /// /// /// A VSS_ROLLFORWARD_TYPE enumeration value indicating the type of roll-forward operation to be performed. /// /// A string specifying the roll-forward restore point. /// /// The format of this string is defined by the writer, and can be a timestamp, a log sequence number (LSN), or any marker defined /// by the writer. /// /// /// /// The SetRollForward method can only be called during a restore operation. /// /// 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/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setrollforward HRESULT // SetRollForward( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, // [in] VSS_ROLLFORWARD_TYPE rollType, [in] LPCWSTR wszRollForwardPoint ); void SetRollForward(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, VSS_ROLLFORWARD_TYPE rollType, string wszRollForwardPoint); ///

The SetSelectedForRestore method indicates whether the specified selectable component is selected for restoration.

/// Writer identifier. /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. /// /// String containing the logical path of the component. For more information, see Logical Pathing of Components. /// The value of the string containing the logical path used here should be the same as was used when the component was added. /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the component. /// /// The string cannot be and should contain the same component name as was used when the component was added /// to the backup set using IVssBackupComponents::AddComponent. /// /// /// /// If the value of this parameter is true, the selected component has been selected for restoration. If the value is /// false, the selected component has not been selected for restoration. /// /// /// SetSelectedForRestore has meaning only for restores taking place in component mode. /// /// SetSelectedForRestore can only be called for components that were explicitly added to the backup document at backup time /// using IVssBackupComponents::AddComponent. Restoring a component that was implicitly selected for backup as part of a component /// set must be done by calling SetSelectedForRestore on the closest ancestor component that was added to the document. If /// only this component's data is to be restored, that should be accomplished through IVssBackupComponents::AddRestoreSubcomponent; /// this can only be done if the component is selectable for restore (see Working with Selectability and Logical Paths). /// /// This method must be called before IVssBackupComponents::PreRestore. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setselectedforrestore HRESULT // SetSelectedForRestore( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR // wszComponentName, [in] bool bSelectedForRestore ); void SetSelectedForRestore(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, bool bSelectedForRestore); ///

/// The SetSelectedForRestoreEx method indicates whether the specified selectable component is selected for restoration to a /// specified writer instance. ///

/// Globally unique identifier (GUID) of the writer class. /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. /// /// String containing the logical path of the component. For more information, see Logical Pathing of Components. /// The value of the string containing the logical path used here should be the same as was used when the component was added. /// The logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. /// /// /// String containing the name of the component. /// /// The string cannot be and should contain the same component name as was used when the component was added /// to the backup set using the IVssBackupComponents::AddComponent method. /// /// /// /// If the value of this parameter is true, the selected component has been selected for restoration. If the value is /// false, the selected component has not been selected for restoration. /// /// /// GUID of the writer instance. /// The default value for this parameter is Guid.Null. /// /// /// /// SetSelectedForRestoreEx, which moves a component to a different writer instance, can be called only for a writer that /// supports running multiple writer instances with the same class ID and supports a requester moving a component to a different /// writer instance at restore time. To determine whether a writer provides this support, call the /// IVssExamineWriterMetadata::GetBackupSchema method. /// /// SetSelectedForRestoreEx has meaning only for restores taking place in component mode. /// /// SetSelectedForRestoreEx can be called only for components that were explicitly added to the backup document at backup /// time using AddComponent. Restoring a component that was implicitly selected for backup as part of a component set must be done /// by calling SetSelectedForRestoreEx on the closest ancestor component that was added to the document. If only this /// component's data is to be restored, that should be accomplished through the IVssBackupComponents::AddRestoreSubcomponent method; /// this can be done only if the component is selectable for restore (see Working with Selectability and Logical Paths). /// /// This method must be called before the IVssBackupComponents::PreRestore method. /// /// The distinction between the instanceId and writerID parameters is necessary because it is possible that multiple instances of /// the same writer are running on the computer. /// /// /// If the value of the instanceId parameter is Guid.Null, this is equivalent to calling the /// IVssBackupComponents::SetSelectedForRestore method. /// /// /// The instanceId parameter is used to specify that the component is to be restored to a different writer instance. If the value of /// the instanceId parameter is not Guid.Null, it must match the instance ID of a writer instance with the same writer class ID /// specified in in the writerID parameter. /// /// /// A writer's class identifier, instance identifier, and instance name can be found by calling the /// IVssExamineWriterMetadataEx::GetIdentityEx method. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex-setselectedforrestoreex HRESULT // SetSelectedForRestoreEx( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, bool // bSelectedForRestore, VSS_ID instanceId ); void SetSelectedForRestoreEx(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, bool bSelectedForRestore, Guid instanceId = default); ///

The StartSnapshotSet method creates a new, empty shadow copy set.

/// The address of a caller-allocated variable that receives the shadow copy set identifier. /// This method must be called before IVssBackupComponents::PrepareForBackup during backup operations. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-startsnapshotset HRESULT // StartSnapshotSet( [out] VSS_ID *pSnapshotSetId ); Guid StartSnapshotSet(); ///

Unexposes a shadow copy either by deleting the file share or by removing the drive letter or mounted folder.

/// /// The shadow copy identifier. The value of this identifier should be the same as the value that was used when the shadow copy was exposed. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-unexposesnapshot HRESULT // UnexposeSnapshot( [in] VSS_ID snapshotId ); void UnexposeSnapshot(Guid snapshotId); } ///

/// /// The IVssExamineWriterMetadata interface allows a requester to examine the metadata of a specific writer instance. This /// metadata may come from a currently executing (live) writer, or it may have been stored as an XML document. /// /// An IVssExamineWriterMetadata interface to a live writer's metadata is obtained by a call to IVssBackupComponents::GetWriterMetadata. /// /// Metadata obtained from a stored XML document can be examined by an instance of IVssExamineWriterMetadata obtained by a call /// to CreateVssExamineWriterMetadata. /// ///

// https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssexaminewritermetadata [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssExamineWriterMetadata")] public interface IVssExamineWriterMetadata { ///

The AlternateLocationMappings property obtains alternate location mappings of a file set.

/// /// /// The value returned by IVssExamineWriterMetadata::GetAlternateLocationMapping should not be confused with that returned by IVssComponent::GetAlternateLocationMapping. /// /// IVssComponent::GetAlternateLocationMapping is the alternate location to which a file was restored. /// /// IVssExamineWriterMetadata::GetAlternateLocationMapping is the alternate location mapping to which a file may be restored /// if necessary. /// /// 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 may 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. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getalternatelocationmapping // HRESULT GetAlternateLocationMapping( [in] UINT iMapping, [out] IVssWMFiledesc **ppFiledesc ); IReadOnlyList AlternateLocationMappings { get; } ///

/// The BackupSchema property is used by a requester to determine from the Writer Metadata Document the types of backup /// operations that a given writer can participate in. ///

/// /// The types of backup operations that a given writer supports, expressed as a bit mask (or bitwise OR) of VSS_BACKUP_SCHEMA /// enumeration values. /// /// /// /// The default backup schema is 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. /// /// The writer calls IVssCreateWriterMetadata::SetBackupSchema to indicate its supported schema in its Writer Metadata Document. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getbackupschema HRESULT // GetBackupSchema( DWORD *pdwSchemaMask ); VSS_BACKUP_SCHEMA BackupSchema { get; } ///

The Components property obtains the Writer Metadata Documents.

/// List of IVssWMComponent objects containing the component information. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getcomponent HRESULT // GetComponent( [in] UINT iComponent, [out] IVssWMComponent **ppComponent ); IReadOnlyList Components { get; } ///

The ExcludeFiles property obtains information about files that have been explicitly excluded from backup.

/// For more information on excluding files, see Exclude File List Specification. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getexcludefile HRESULT // GetExcludeFile( [in] UINT iFile, [out] IVssWMFiledesc **ppFiledesc ); IReadOnlyList ExcludeFiles { get; } ///

Obtains information about file sets that have been explicitly excluded.

/// /// The GetExcludeFromSnapshotFile method is intended to report information about file sets excluded from a shadow copy. /// Requesters should not exclude files from backup based on the information returned by this method. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex2-getexcludefromsnapshotfile // HRESULT GetExcludeFromSnapshotFile( [in] UINT iFile, [out] IVssWMFiledesc **ppFiledesc ); IReadOnlyList ExcludeFromSnapshotFiles { get; } ///

Obtains the version information for a writer application.

/// The version of the writer application. /// /// The GetVersion method returns nonzero results only if the writer was initialized by calling the /// CVssWriterEx::InitializeEx method and explicit version information was specified. If the writer is initialized by calling the /// CVssWriter::Initialize method, or if no version information was specified in the call to the CVssWriterEx::InitializeEx /// method, the GetVersion method returns zero in the Major and Minor fields. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex2-getversion HRESULT // GetVersion( [out] DWORD *pdwMajorVersion, [out] DWORD *pdwMinorVersion ); Version Version { get; } ///

/// The GetIdentityEx method obtains the writer instance name and other basic information about a specific writer instance. ///

/// Globally unique identifier (GUID) of the writer instance. /// GUID of the writer class. /// A string specifying the name of the writer. /// A string specifying the writer instance name. /// A VSS_USAGE_TYPE enumeration value indicating how the data managed by the writer is used on the host system. /// A VSS_SOURCE_TYPE enumeration value indicating the type of data managed by the writer. /// /// This method is identical to the IVssExamineWriterMetadata::GetIdentity method except for the pbstrInstanceName parameter. /// The pbstrInstanceName parameter is the writer instance name that was specified during writer initialization by CVssWriter::Initialize. /// /// The writer instance name is useful for writers that support running multiple writer instances with the same writer class ID on a /// single computer. The writer instance name can be used to identify the specific instance. Therefore, the writer must make the /// instance name unique within the writer class. Also, the writer instance name is expected to persist between backup and restore, /// and it is used by VSS to correctly restore multiple-instance writers. /// /// The caller must free the memory held by the pbstrWriterName and pbstrInstanceName parameters by calling SysFreeString. /// /// An IVssExamineWriterMetadataEx interface might be from stored writer state information (created by a call to /// CreateVssExamineWriterMetadata). If this is the case, then the following are true: /// /// /// /// pidInstance may not mean anything in terms of live writers. /// /// /// If pidWriter does not match the writer class of any live writer, a requester should not use that writer's components. /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex-getidentityex HRESULT // GetIdentityEx( [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter, [out] BSTR *pbstrWriterName, [out] BSTR // *pbstrInstanceName, [out] VSS_USAGE_TYPE *pUsage, [out] VSS_SOURCE_TYPE *pSource ); void GetIdentity(out Guid pidInstance, out Guid pidWriter, out string pbstrWriterName, out string pbstrInstanceName, out VSS_USAGE_TYPE pUsage, out VSS_SOURCE_TYPE pSource); ///

The GetRestoreMethod method returns information about how a writer wants its data to be restored.

/// /// A VSS_RESTOREMETHOD_ENUM value that specifies file overwriting, the use of alternate locations specifying the method that will /// be used in the restore operation. /// /// /// If the value of pMethod is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, a pointer to a string containing the name /// of the service that is started and stopped. Otherwise, the value is . /// /// /// Pointer to the URL of an HTML or XML document describing to the user how the restore is to be performed. The value may be . /// /// /// A VSS_WRITERRESTORE_ENUM value specifying whether the writer will be involved in restoring its data. /// /// /// A Boolean value indicating whether a reboot will be required after the restore operation is complete. The value receives /// true if a reboot will be required, or false otherwise. /// /// Pointer to the number of alternate mappings associated with the writer. /// /// The caller must free the memory used by the pbstrUserProcedure and pbstrService parameters by calling SysFreeString. /// 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 : /// /// /// 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, a requester uses the name returned by /// pbstrService to determine which service must be stopped during and then restarted after restore. See Stopping Services For /// Restore by Requesters for information on writer participation in stopping and restarting services during a restore operation. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getrestoremethod HRESULT // GetRestoreMethod( [out] VSS_RESTOREMETHOD_ENUM *pMethod, [out] BSTR *pbstrService, [out] BSTR *pbstrUserProcedure, [out] // VSS_WRITERRESTORE_ENUM *pwriterRestore, [out] bool *pbRebootRequired, [out] UINT *pcMappings ); void GetRestoreMethod(out VSS_RESTOREMETHOD_ENUM pMethod, out string pbstrService, out string pbstrUserProcedure, out VSS_WRITERRESTORE_ENUM pwriterRestore, out bool pbRebootRequired, out uint pcMappings); ///

/// The LoadFromXML method loads an XML document that contains a writer's metadata document into an IVssExamineWriterMetadata interface. ///

/// String that contains an XML document that represents a writer's metadata document. /// /// /// This method is used at restore time to load writer metadata that was saved by IVssExamineWriterMetadata::SaveAsXML at the time /// of the backup operation. /// /// Users should not tamper with this metadata document. /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-loadfromxml HRESULT // LoadFromXML( [in] BSTR bstrXML ); void LoadFromXML(string bstrXML); ///

/// The SaveAsXML method saves the Writer Metadata Document that contains a writer's state information to a specified string. /// This string can be saved as part of a backup operation. ///

/// The Writer Metadata Document that contains a writer's state information. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-saveasxml HRESULT SaveAsXML( // [in] BSTR *pbstrXML ); string SaveAsXML(); } ///

/// The IVssWMComponent allows access to component information stored in a Writer Metadata Document. /// Instances of IVssWMComponent are obtained by calling IVssExamineWriterMetadata::GetComponent. ///

// https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivsswmcomponent [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssWMComponent")] public interface IVssWMComponent { ///

/// The DatabaseFiles property obtains a list of IVssWMFiledesc objects containing information about the database backup /// component files. ///

/// List of IVssWMFiledesc objects containing the returned file descriptor information. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdatabasefile HRESULT GetDatabaseFile( // [in] UINT iDBFile, [out] IVssWMFiledesc **ppFiledesc ); IReadOnlyList DatabaseFiles { get; } ///

/// The DatabaseLogFiles property obtains file descriptors for the log file associated with the database backup component. ///

/// List of IVssWMFiledesc objects containing the returned file descriptor information. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdatabaselogfile HRESULT // GetDatabaseLogFile( [in] UINT iDbLogFile, [out] IVssWMFiledesc **ppFiledesc ); IReadOnlyList DatabaseLogFiles { get; } ///

/// The Dependencies property returns a list of IVssWMDependency interfaces containing accessors for obtaining information /// about explicit writer-component dependencies of the current components. ///

/// List of IVssWMDependency interfaces. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdependency HRESULT GetDependency( [in] // UINT iDependency, [out] IVssWMDependency **ppDependency ); IReadOnlyList Dependencies { get; } ///

The Files property obtains the file descriptors associated with the component.

/// List of IVssWMFiledesc objects containing the returned file descriptor information. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getfile HRESULT GetFile( [in] UINT iFile, // [out] IVssWMFiledesc **ppFiledesc ); IReadOnlyList Files { get; } ///

The GetComponentInfo method obtains basic information about the specified writer metadata component.

/// A structure containing the returned component information. /// The caller is responsible for freeing the returned VSS_COMPONENTINFO structure by calling IVssWMComponent::FreeComponentInfo. // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getcomponentinfo HRESULT // GetComponentInfo( [out] PVSSCOMPONENTINFO *ppInfo ); VSS_COMPONENTINFO GetComponentInfo(); } ///

/// /// The IVssWriterComponentsExt interface is used by requesters to access and modify the components of a writer involved in a backup. /// /// /// IVssWriterComponentsExt is returned by IVssBackupComponents::GetWriterComponents and inherits from IVssWriterComponents and IUnknown. /// /// /// Note During the restore phase, the requester should call IVssWriterComponentsExt::GetComponent or /// IVssWriterComponentsExt::GetComponentCount only after the call to IVssBackupComponents::PreRestore has returned, to allow time for /// the writer to update the Backup Components Document. One example of such an update would be to change the restore target. /// /// Life cycle management of IVssWriterComponentsExt is handled through the inherited IUnknown methods. /// IVssWriterComponentsExt does not define any methods. ///

// https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivsswritercomponentsext [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssWriterComponentsExt")] public interface IVssWriterComponentsExt : IVssWriterComponents { } ///

/// The VSS_COMPONENTINFO structure contains information about a given component, and is returned to requesters by the /// IVssWMComponent interface. ///

/// /// /// To obtain VSS_COMPONENTINFO object for a given component, a requester must first obtain the corresponding IVssWMComponent /// object through a call to IVssExamineWriterMetadata::GetComponent. A call to IVssWMComponent::GetComponentInfo then allocates and /// returns a VSS_COMPONENTINFO structure. /// /// /// Because VSS_COMPONENTINFO is allocated and returned by IVssWMComponent::GetComponentInfo, a requester should not free a /// VSS_COMPONENTINFO object directly, but should use IVssWMComponent::FreeComponentInfo. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/ns-vsbackup-vss_componentinfo typedef struct _VSS_COMPONENTINFO { // VSS_COMPONENT_TYPE type; BSTR bstrLogicalPath; BSTR bstrComponentName; BSTR bstrCaption; BYTE *pbIcon; UINT cbIcon; bool // bRestoreMetadata; bool bNotifyOnBackupComplete; bool bSelectable; bool bSelectableForRestore; DWORD dwComponentFlags; UINT // cFileCount; UINT cDatabases; UINT cLogFiles; UINT cDependencies; } VSS_COMPONENTINFO; [PInvokeData("vsbackup.h", MSDNShortId = "NS:vsbackup._VSS_COMPONENTINFO")] [StructLayout(LayoutKind.Sequential)] public struct VSS_COMPONENTINFO { ///

Component type. See VSS_COMPONENT_TYPE.

public VSS_COMPONENT_TYPE type; ///

/// A string containing the logical path of the component. /// A logical path can be . /// There are no restrictions on the characters that can appear in a non- logical path. ///

public string bstrLogicalPath; ///

A string containing the name of the component. A component name string cannot be .

public string bstrComponentName; ///

A string containing the description of the component. A caption string can be .

public string bstrCaption; ///

/// /// A buffer containing the binary data for a displayable icon representing the component. The buffer contents should use the same /// format as the standard icon(.ico) files. The size, in bytes, of the buffer is specified by cbIcon. /// /// If the writer that created the component did not choose to specify an icon, pbIcon is . ///

public byte[] pbIcon; ///

/// /// Boolean that indicates whether there is private metadata associated with the restoration of the component. The Boolean is /// true if there is metadata and false if there is not. /// /// /// A writer indicates whether a component supports private metadata by setting this value when a component is added with /// IVssCreateWriterMetadata::AddComponent. Writers later add restore metadata with IVssComponent::SetRestoreMetadata. Requesters /// retrieve the information using IVssComponent::GetRestoreMetadata. /// ///

public bool bRestoreMetadata; ///

Reserved for future use. The value of this parameter should always be set to false.

public bool bNotifyOnBackupComplete; ///

/// /// Boolean that indicates(for component mode operations) if the component is selectable for backup. The value of bSelectable /// helps determine whether a requester has the option of including or excluding a given component in backup operations. The Boolean /// is true if the component is selectable for backup and false if it is not. /// /// /// There is no default value for a component's selectability for backup. A writer must always explicitly set the value when it adds /// the component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent. /// /// /// In addition, the value of bSelectable, the component's logical path, and the component's relationship to other components /// as expressed in that path determine when and how a component is included in a backup operation: /// /// /// /// /// For a nonselectable for backup component( bSelectable is false) with no selectable for backup ancestors in the /// hierarchy of its logical path, inclusion in the backup set is always mandatory and always implicit. A requester explicitly adds /// the component to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. /// /// /// /// /// For a selectable for backup component( bSelectable is true) with no selectable for backup ancestor in the /// hierarchy of its logical paths, inclusion in the backup set is always optional and always explicit. A requester explicitly adds /// the component to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. /// /// If such a component is included as an ancestor in the logical path of other components, both those that are selectable for /// backup and those that are not, it defines a component set containing these other components as subcomponents. If a selectable /// for backup component is explicitly included in a backup, these subcomponents are implicitly included in the backup. /// /// /// /// /// /// For a nonselectable for backup component( bSelectable is false) that has a selectable for backup ancestor in the /// hierarchy of its logical paths(and are therefore part of a component set defined by that ancestor), inclusion in the backup set /// is always implicit and contingent on the inclusion of a selectable for backup ancestor. A requester never explicitly adds the /// component to the backup set in the Backup Components Document; instead, it adds the selectable for backup ancestor to the /// document using IVssBackupComponents::AddComponent. /// /// /// /// /// For a selectable for backup component( bSelectable is true) that has a selectable for backup ancestor in the /// hierarchy of its logical paths(and is therefore part of a component set defined by that ancestor), inclusion in the backup set /// can be either optional and explicit, or if the component is not explicitly selected, its inclusion may be implicit and /// contingent on the inclusion of a selectable for backup ancestor. If the inclusion of the component is explicit, a requester /// explicitly adds the components to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. /// If the inclusion is implicit, a requester does not add these components to a backup set in the Backup Components Document. /// /// If the inclusion of the component is explicit and the component defines a component set, the members of that component set are /// implicitly selected. /// /// /// A writer sets a component's selectability for backup( bSelectable) when adding the component to the Writer Metadata /// Document by using IVssCreateWriterMetadata::AddComponent. /// /// See Working with Selectability and Logical Paths for more information. /// /// /// ///

public bool bSelectable; ///

/// /// Boolean that indicates(for component-mode operations) whether the component is selectable for restore. /// bSelectableForRestore allows the requester to determine whether this component can be individually selected for restore /// if it had earlier been implicitly included in the backup. The Boolean is true if the component is selectable for restore /// and false if it is not. /// /// /// By default, a component's selectability for restore is false. A writer can override this default when it adds the /// component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent. /// /// /// If a component is explicitly added to the backup document(see explicit component inclusion), then it can always be individually /// selected for restore; so this flag then has no meaning. If a component is implicitly added to the backup document, then the /// bSelectableForRestore flag determines whether the component can be individually restored using IVssBackupComponents::AddRestoreSubcomponent. /// /// See Working with Selectability and Logical Paths for more information. ///

public bool bSelectableForRestore; ///

/// A bit mask(or bitwise OR) of values of the VSS_COMPONENT_FLAGS enumeration, indicating the features this component supports. /// Windows Server 2003 and Windows XP: Before Windows Server 2003 with SP1, this member is reserved for system use. ///

public VSS_COMPONENT_FLAGS dwComponentFlags; ///

/// If the component is a file group, the number of file descriptors for files in the group. Otherwise, this value is zero. ///

public uint cFileCount; ///

If the component is a database, the number of database file descriptors. Otherwise, this value is zero.

public uint cDatabases; ///

/// If the component is a database, the number of database log file descriptors. Otherwise, the value of this parameter is zero. ///

public uint cLogFiles; ///

/// The number of explicit writer-component dependencies of the current component. This value is incremented when /// IVssCreateWriterMetadata::AddComponentDependency is called by a writer. ///

public uint cDependencies; } ///

Status of a writer.

public struct VssWriterStatus { ///

/// The address of a variable that receives the application failure message that the writer passed for the wszApplicationMessage /// parameter of the SetWriterFailureEx method. This parameter is optional and can be NULL. ///

public string pbstrApplicationMessage; ///

The address of a caller-allocated variable that receives a string containing the name of the specified writer.

public string pbstrWriter; ///

/// The address of a caller-allocated variable that receives the return code that the writer passed for the hrApplication parameter /// of the CVssWriterEx2::SetWriterFailureEx method. This parameter is optional and can be NULL. ///

public HRESULT phrApplication; ///

/// The address of a caller-allocated variable that receives the HRESULT failure code that was returned by the writer. /// The following are the supported values for pHrResultFailure. /// /// /// 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. Windows Vista, Windows Server 2003 and Windows XP: This value is not supported. /// /// /// ///

public HRESULT phResultFailure; ///

The address of a caller-allocated variable that receives the instance identifier of the writer.

public Guid pidInstance; ///

The address of a caller-allocated variable that receives the identifier for the writer class.

public Guid pidWriter; ///

The address of a caller-allocated variable that receives a VSS_WRITER_STATE enumeration value.

public VSS_WRITER_STATE pnStatus; } ///

VSS information methods.

public static class VssInfo { private const string Lib_VssApi = "vssapi.dll"; ///

/// The IsVolumeSnapshotted function determines whether any shadow copies exist for the specified volume. /// /// Note This function is exported as IsVolumeSnapshottedInternal, but you should call IsVolumeSnapshotted, not IsVolumeSnapshottedInternal. /// ///

/// /// /// Name of the volume. The name of the volume to be checked must be in one of the following formats and must include a trailing backslash(\): /// /// /// /// The path of a mounted folder, for example, Y:\MountX\ /// /// /// A drive letter, for example, D:\ /// /// /// A volume GUID path of the form \\?\Volume{GUID}\(where GUID identifies the volume) /// /// /// /// /// The value of this parameter is TRUE if the volume has a shadow copy, and FALSE if the volume does not have a /// shadow copy. /// /// /// A bit mask(or bitwise OR) of VSS_SNAPSHOT_COMPATIBILITY values that indicates whether certain volume control or file I/O /// operations are disabled for the given volume if a shadow copy of it exists. /// /// /// /// The return values listed here are in addition to the normal COM HRESULT s that may be returned at any time from the function. /// /// /// /// Value /// Meaning /// /// /// S_OK /// The function completed successfully. /// /// /// E_ACCESSDENIED /// The caller does not have sufficient backup privileges or is not an administrator. /// /// /// E_INVALIDARG /// One of the parameters is not valid. /// /// /// E_OUTOFMEMORY /// Out of memory or other system resources. /// /// /// VSS_E_PROVIDER_VETO /// /// Expected provider error. The provider logged the error in the event log. For more information, see Event and Error Handling /// Under VSS. /// /// /// /// VSS_E_OBJECT_NOT_FOUND /// The specified volume was not found. /// /// /// VSS_E_UNEXPECTED /// /// Unexpected error. The error code is logged in the error log file. For more information, see Event and Error Handling Under VSS. /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported until Windows Server 2008 R2 /// and Windows 7. E_UNEXPECTED is used instead. /// /// /// /// VSS_E_UNEXPECTED_PROVIDER_ERROR /// /// Unexpected provider error. The error code is logged in the event log file. For additional information, see Event and Error /// Handling Under VSS. /// /// /// /// /// /// Before calling this function, the caller must have initialized COM by calling the CoInitialize function. /// /// If no volume control or file I/O operations are disabled for the selected volume, then the shadow copy capability of the /// selected volume returned by plSnapshotCapability will be zero. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-isvolumesnapshotted HRESULT IsVolumeSnapshotted( [in] // VSS_PWSZ pwszVolumeName, [out] BOOL *pbSnapshotsPresent, [out] LONG *plSnapshotCapability); [DllImport(Lib_VssApi, SetLastError = false, CharSet = CharSet.Unicode, EntryPoint = "IsVolumeSnapshottedInternal")] [PInvokeData("vsbackup.h", MSDNShortId = "NF:vsbackup.IsVolumeSnapshotted")] public static extern HRESULT IsVolumeSnapshotted(string pwszVolumeName, [MarshalAs(UnmanagedType.Bool)] out bool pbSnapshotsPresent, out VSS_SNAPSHOT_COMPATIBILITY plSnapshotCapability); ///

Checks the registry for writers that should block revert operations on the specified volume.

/// /// The name of the volume. This name must be in one of the following formats and must include a trailing backslash(\): /// /// /// The path of a mounted folder, for example, Y:\MountX\ /// /// /// A drive letter, for example, D:\ /// /// /// A volume GUID path of the form \\?\Volume{GUID}\(where GUID identifies the volume) /// /// /// /// /// A variable that receives true if the volume contains components from any writers that are listed in the registry as /// writers that should block revert operations, or false otherwise. /// /// /// This function can return one of these values. /// /// /// Value /// Meaning /// /// /// S_OK /// The function succeeded. /// /// /// E_ACCESSDENIED /// The caller is not an administrator. /// /// /// E_INVALIDARG /// One of the parameter values is not valid. /// /// /// E_OUTOFMEMORY /// The caller is out of memory or other system resources. /// /// /// VSS_E_UNEXPECTED /// /// Unexpected error. The error code is logged in the error log file. For more information, see Event and Error Handling Under VSS. /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported until Windows Server 2008 R2 /// and Windows 7. E_UNEXPECTED is used instead. /// /// /// /// /// /// The list of writers that should block revert operations is stored in the registry under the following key: /// HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\VSS\Settings\WritersBlockingRevert /// // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-shouldblockrevert HRESULT ShouldBlockRevert( [in] LPCWSTR // wszVolumeName, [out] bool *pbBlock); [DllImport(Lib_VssApi, SetLastError = false, ExactSpelling = true, EntryPoint = "ShouldBlockRevertInternal")] [PInvokeData("vsbackup.h", MSDNShortId = "NF:vsbackup.ShouldBlockRevert")] public static extern HRESULT ShouldBlockRevert([MarshalAs(UnmanagedType.LPWStr)] string wszVolumeName, [MarshalAs(UnmanagedType.Bool)] out bool pbBlock); } }