diff --git a/PInvoke/VssApi/vsbackup.cs b/PInvoke/VssApi/vsbackup.cs
index eb3883aa..9d8f94b3 100644
--- a/PInvoke/VssApi/vsbackup.cs
+++ b/PInvoke/VssApi/vsbackup.cs
@@ -4,91 +4,6 @@ using System.Runtime.InteropServices;
namespace Vanara.PInvoke.VssApi
{
- /// Status of a writer.
- public struct VssWriterStatus
- {
- /// 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 string containing the name of the specified writer.
- ///
- public string pbstrWriter;
- /// The address of a caller-allocated variable that receives a VSS_WRITER_STATE enumeration value.
- public VSS_WRITER_STATE pnStatus;
- ///
- /// 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 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 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 IVssBackupComponents interface is used by a requester to poll writers about file status and to run backup/restore operations.
@@ -96,30 +11,23 @@ namespace Vanara.PInvoke.VssApi
/// 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.
///
- /// After the backup, restore, or Query operation has either successfully finished or been explicitly terminated, a requester must
- /// release the IVssBackupComponents object by calling IVssBackupComponents::Release. 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.
+ /// 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")]
- //[ComImport, Guid("665c1d5f-c218-414d-a05d-7fef5f9d5c86"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IVssBackupComponents
{
///
- /// The GetWriterComponents method is used to return information about those components of a given writer that have been
- /// stored in a requester's Backup Components Document.
+ /// The GetWriterComponents method is used to return information about those components that have been stored in a
+ /// requester's Backup Components Document.
///
- ///
- /// The index of the writer being queried. It is a number between 0 and n-1, where n is the value returned by IVssBackupComponents::GetWriterComponentsCount.
- ///
- /// An IVssWriterComponentsExt interface object that will receive the returned component information.
+ /// A list of IVssWriterComponentsExt interface objects with the returned component information.
///
- /// The caller of this method must call IUnknown::Release when it finishes accessing the component information.
///
- /// GetWriterComponents retrieves component information for a component stored in the Backup Components Document by earlier
- /// calls to IVssBackupComponents::AddComponent.
+ /// 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
@@ -143,103 +51,16 @@ namespace Vanara.PInvoke.VssApi
// GetWriterComponents( [in] UINT iWriter, [out] IVssWriterComponentsExt **ppWriter );
IReadOnlyList WriterComponents { get; }
- /// 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 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 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 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);
-
- ///
- /// 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 GetWriterMetadata method returns the metadata for a specific writer running on the system.
- ///
- /// Index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 inclusive, where
- /// n is the total number of writers on the current system. The value of n is returned by IVssBackupComponents::GetWriterMetadataCount.
- ///
- /// Pointer to the instance identifier of the writer that collected the metadata.
- /// Doubly indirect pointer to the instance of the IVssExamineWriterMetadata object that contains the returned metadata.
+ /// 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 GetWriterMetadata.
+ /// calling WriterMetadata.
///
///
/// Although IVssBackupComponents::GatherWriterMetadata must be called prior to either a restore or backup operation,
- /// GetWriterMetadata is not typically called for restores.
+ /// WriterMetadata is not typically called for restores.
///
///
/// Component information retrieved (during backup operations) using IVssExamineWriterMetadata::GetComponent, where the
@@ -250,120 +71,26 @@ namespace Vanara.PInvoke.VssApi
/// 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.
///
- /// When the caller of this method is finished accessing the metadata, it must call IUnknown::Release.
///
// 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 FreeWriterMetadata method frees system resources allocated when IVssBackupComponents::GatherWriterMetadata was called.
- ///
+ /// The WriterStatus property returns the status of the writers.
///
///
- /// 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.
+ /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterStatus and wait for it to complete prior to
+ /// calling WriterStatus.
///
///
- /// 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.
+ /// 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-freewritermetadata HRESULT FreeWriterMetadata();
- void FreeWriterMetadata();
-
- ///
- /// 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 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.
- ///
- ///
- /// Doubly indirect pointer to 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();
+ // 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.
@@ -379,486 +106,6 @@ namespace Vanara.PInvoke.VssApi
// https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-abortbackup HRESULT AbortBackup();
void AbortBackup();
- /// The GatherWriterStatus method prompts each writer to send a status message.
- /// Doubly indirect pointer to 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();
-
- /// 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 GetWriterStatus method returns the status of the specified writer.
- ///
- /// Index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 inclusive, where
- /// n is the total number of writers on the current system. The value of n is returned by IVssBackupComponents::GetWriterStatusCount.
- ///
- /// The address of a caller-allocated variable that receives the instance identifier of the writer.
- /// The address of a caller-allocated variable that receives the identifier for the writer class.
- ///
- /// The address of a caller-allocated variable that receives a string containing the name of the specified writer.
- ///
- /// The address of a caller-allocated variable that receives a VSS_WRITER_STATE enumeration value.
- ///
- /// 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.
- ///
- ///
- ///
- ///
- ///
- ///
- /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterStatus and wait for it to complete prior to
- /// calling GetWriterStatus.
- ///
- ///
- /// When the caller has finished accessing the status information returned by this method, it should call SysFreeString to free the
- /// memory held by the pbstrWriter parameter.
- ///
- ///
- /// 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 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 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 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 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 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);
-
- ///
- ///
- /// 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 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 BackupComplete method causes VSS to generate a BackupComplete event, which signals writers that the backup
- /// process has completed.
- ///
- /// Doubly indirect pointer to 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.
- ///
- /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned IVssAsync
- /// when it is no longer needed.
- ///
- ///
- // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-backupcomplete HRESULT
- // BackupComplete( [out] IVssAsync **ppAsync );
- IVssAsync BackupComplete();
-
///
/// 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.
@@ -982,93 +229,73 @@ namespace Vanara.PInvoke.VssApi
string wszComponentName, string wszPath, string wszFilespec, bool bRecursive, string wszDestination);
///
- /// 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.
+ /// 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 possible return values.
+ ///
+ /// 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 component in the backup document that defines the backup component set containing the
- /// subcomponent to be added for restore.
+ /// String containing the logical path of the selectable for backup component. For more information, see Logical Pathing of Components.
///
- /// The value of this parameter can be .
+ /// 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 logical path of the component in the backup document that defines the backup component set containing the
- /// subcomponent to be added for restore.
- ///
+ /// 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- 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
///
+ /// 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.
+ ///
+ ///
///
- /// 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.
+ /// 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).
///
///
- /// 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.
+ /// 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.
///
- /// 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);
-
- /// The SetFileRestoreStatus method indicates whether some, all, or no files were successfully restored.
- /// 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 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 all of the files were restored, the value of this parameter is VSS_RS_ALL. If some of the files were restored, the value of
- /// this parameter is VSS_RS_FAILED. If none of the files were restored, the value of this parameter is VSS_RS_NONE.
- ///
- /// This method should be called between calls to IVssBackupComponents::PreRestore and IVssBackupComponents::PostRestore.
- // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setfilerestorestatus HRESULT
- // SetFileRestoreStatus( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR
- // wszComponentName, [in] VSS_FILE_RESTORE_STATUS status );
- void SetFileRestoreStatus(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath,
- string wszComponentName, VSS_FILE_RESTORE_STATUS status);
+ // 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
@@ -1170,106 +397,80 @@ namespace Vanara.PInvoke.VssApi
string wszPath, string wszFileName, bool bRecursive, string wszAlternatePath);
///
- /// 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.
+ /// 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.
///
- ///
- /// Globally unique identifier (GUID) of the writer class containing the files involved in the partial file operation.
+ /// Writer class identifier.
+ ///
+ /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for possible return values.
///
- /// 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.
+ /// 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 logical path can be .
+ /// 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 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.
+ /// 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.
///
- ///
- /// 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 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 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);
+ ///
+ /// 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);
///
- /// The PreRestore method will cause VSS to generate a PreRestore event, signaling writers to prepare for an upcoming restore operation.
+ /// Specifies the volumes to be included in a LUN resynchronization operation. This method is supported only on Windows server
+ /// operating systems.
///
- /// Doubly indirect pointer to 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 PostRestore method will cause VSS to generate a PostRestore event, signaling writers that the current restore
- /// operation has finished.
- ///
- /// Doubly indirect pointer to 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();
-
- /// 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 identifier of the shadow copy that was returned by the IVssBackupComponents::AddToSnapshotSet method during backup. This
+ /// parameter is required and cannot be Guid.Null.
///
- ///
- /// 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 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();
+ /// 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.
///
@@ -1331,24 +532,81 @@ namespace Vanara.PInvoke.VssApi
// AddToSnapshotSet( [in] VSS_PWSZ pwszVolumeName, [in] VSS_ID ProviderId, [out] VSS_ID *pidSnapshot );
Guid AddToSnapshotSet(string pwszVolumeName, Guid ProviderId);
- /// Commits all shadow copies in this set simultaneously.
- ///
- /// A doubly indirect pointer to the required IVssAsync asynchronous interface. This is used to query the method execution state and
- /// to retrieve the final error code.
- ///
+ ///
+ /// The BackupComplete method causes VSS to generate a BackupComplete event, which signals writers that the backup
+ /// process has completed.
+ ///
+ /// An IVssAsync instance.
///
- /// 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.
+ /// 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-dosnapshotset HRESULT DoSnapshotSet(
- // [out] IVssAsync **ppAsync );
- IVssAsync DoSnapshotSet();
+ // 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.
@@ -1382,46 +640,294 @@ namespace Vanara.PInvoke.VssApi
void DeleteSnapshots(Guid SourceObjectId, VSS_OBJECT_TYPE eSourceObjectType, bool bForceDelete,
out int plDeletedSnapshots, out Guid pNondeletedSnapshotID);
- /// The ImportSnapshots method imports shadow copies transported from a different machine.
- /// Doubly indirect pointer to an IVssAsync object containing the imported shadow copy status data.
+ /// The DisableWriterClasses method prevents a specific class of writers from receiving any events.
+ /// An array containing one or more writer class identifiers.
///
- /// 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.
+ /// 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.
///
///
- /// 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.
+ /// 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-importsnapshots HRESULT
- // ImportSnapshots( [out] IVssAsync **ppAsync );
- IVssAsync ImportSnapshots();
+ // 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 BreakSnapshotSet method causes the existence of a shadow copy set to be "forgotten" by VSS.
- /// Shadow copy set identifier.
+ /// The DisableWriterInstances method disables a specified writer instance or instances.
+ /// An array containing one or more writer instance identifiers.
///
///
- /// BreakSnapshotSet can be used only for shadow copies created by a hardware shadow copy provider. This method makes these
- /// shadow copies regular volumes.
+ /// 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.
///
///
- /// 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.
+ /// 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-breaksnapshotset HRESULT
- // BreakSnapshotSet( [in] VSS_ID SnapshotSetId );
- void BreakSnapshotSet(Guid SnapshotSetId);
+ // 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.
@@ -1441,44 +947,57 @@ namespace Vanara.PInvoke.VssApi
// GetSnapshotProperties( [in] VSS_ID SnapshotId, [out] VSS_SNAPSHOT_PROP *pProp );
VSS_SNAPSHOT_PROP GetSnapshotProperties(Guid SnapshotId);
- ///
- /// 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.
- ///
- /// Doubly indirect pointer to an IVssEnumObject enumerator object.
+ /// 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.
///
- /// Because Query returns only information on completed shadow copies, the only shadow copy state it can disclose is VSS_SS_COMPLETED.
+ /// 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.
///
///
- /// 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.
+ /// 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-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);
+ // 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
@@ -1534,139 +1053,164 @@ namespace Vanara.PInvoke.VssApi
///
bool IsVolumeSupported(Guid ProviderId, string pwszVolumeName);
- /// The DisableWriterClasses method prevents a specific class of writers from receiving any events.
- /// An array containing one or more writer class identifiers.
- /// The number of entries in the rgWriterClassId array.
- ///
- ///
- /// 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 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();
- /// The EnableWriterClasses method enables the specified writers to receive all events.
- /// An array containing one or more writer class identifiers.
- /// The number of entries in the rgWriterClassId array.
- ///
- ///
- /// 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);
+ ///
+ /// 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 DisableWriterInstances method disables a specified writer instance or instances.
- /// An array containing one or more writer instance identifiers.
- /// The number of entries in the rgWriterInstanceId array.
- ///
- ///
- /// 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);
-
- /// 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 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.
+ ///
///
- /// 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.
+ /// An instance of the IVssAsync interface that is used to determine when the asynchronous operation is complete.
///
///
///
- /// The caller is responsible for freeing the string that the pwszExposed parameter points to by calling the CoTaskMemFree function.
+ /// PrepareForBackup generates a PrepareForBackup event, which is handled by each instance of each writer through the
+ /// CVssWriter::OnPrepareBackup method.
///
- /// When exposing a persistent shadow copy, it remains exposed through subsequent boots.
+ /// Before PrepareForBackup can be called, IVssBackupComponents::SetBackupState must be called.
///
- /// 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.
+ /// 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.
///
- ///
- /// 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.
+ /// The caller is responsible for releasing the IVssAsync interface.
///
- // 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);
+ // 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);
///
///
@@ -1689,37 +1233,576 @@ namespace Vanara.PInvoke.VssApi
void RevertToSnapshot(Guid SnapshotId, bool bForceDismount);
///
- /// The QueryRevertStatus method returns an IVssAsync interface pointer that can be used to determine the status of the
- /// revert operation.
+ /// 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.
+ ///
///
- /// String containing the name of the volume. The name must be in one of the following formats and must include a trailing backslash (\):
+ /// 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
+ ///
/// -
- /// The path of a mounted folder, for example, Y:\MountX\
+ /// S_OK
+ /// Successfully set the backup options.
///
/// -
- /// A drive letter, for example, D:\
+ /// E_INVALIDARG
+ /// One of the parameter values is not valid.
///
/// -
- /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume)
+ /// 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.
+ ///
///
///
- ///
- ///
- /// An IVssAsync interface pointer that can be used to retrieve the status of the revert process. When the operation is complete,
- /// the caller must release the interface pointer by calling the IUnknown::Release method.
///
///
- /// 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.
+ ///
+ /// 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-queryrevertstatus HRESULT
- // QueryRevertStatus( [in] VSS_PWSZ pwszVolume, [out] IVssAsync **ppAsync );
- IVssAsync QueryRevertStatus(string pwszVolume);
+ // 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.
+ /// 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 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 all of the files were restored, the value of this parameter is VSS_RS_ALL. If some of the files were restored, the value of
+ /// this parameter is VSS_RS_FAILED. If none of the files were restored, the value of this parameter is VSS_RS_NONE.
+ ///
+ /// This method should be called between calls to IVssBackupComponents::PreRestore and IVssBackupComponents::PostRestore.
+ // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setfilerestorestatus HRESULT
+ // SetFileRestoreStatus( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR
+ // wszComponentName, [in] VSS_FILE_RESTORE_STATUS status );
+ void SetFileRestoreStatus(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath,
+ string wszComponentName, VSS_FILE_RESTORE_STATUS status);
+
+ ///
+ ///
+ /// 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
@@ -1788,6 +1871,13 @@ namespace Vanara.PInvoke.VssApi
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.
@@ -1795,281 +1885,12 @@ namespace Vanara.PInvoke.VssApi
// https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-unexposesnapshot HRESULT
// UnexposeSnapshot( [in] VSS_ID snapshotId );
void UnexposeSnapshot(Guid snapshotId);
-
- /// 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);
-
- ///
- /// 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);
-
- /// 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);
-
- /// 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. When the break operation is complete, the IUnknown::Release method must be called for this interface pointer.
- ///
- ///
- ///
- /// 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);
-
- ///
- /// 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);
-
- ///
- /// 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);
-
- ///
- /// 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);
-
- /// 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. When the operation is complete, the caller must release the interface pointer by calling the IUnknown::Release method.
- ///
- ///
- ///
- /// 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);
-
- /// 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();
-
- ///
- /// 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);
}
///
///
- /// The IVssExamineWriterMetadata interface is a C++ (not COM) interface that 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.
+ /// 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.
///
@@ -2295,9 +2116,7 @@ namespace Vanara.PInvoke.VssApi
}
///
- ///
- /// The IVssWMComponent is a C++ (not COM) interface that allows access to component information stored in a Writer Metadata Document.
- ///
+ /// 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
@@ -2337,7 +2156,7 @@ namespace Vanara.PInvoke.VssApi
IReadOnlyList Files { get; }
/// The GetComponentInfo method obtains basic information about the specified writer metadata component.
- /// Doubly indirect pointer to a structure containing the returned component information.
+ /// 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 );
@@ -2346,8 +2165,7 @@ namespace Vanara.PInvoke.VssApi
///
///
- /// The IVssWriterComponentsExt interface is a C++ (not COM) interface used by requesters to access and modify the components of
- /// a writer involved in a backup.
+ /// 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.
@@ -2357,15 +2175,11 @@ namespace Vanara.PInvoke.VssApi
/// 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. Specifically, an
- /// application is responsible for calling IUnknown::Release to release resources held by an IVssWriterComponentsExt object.
- ///
+ /// 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")]
- //[ComVisible(true)]
public interface IVssWriterComponentsExt : IVssWriterComponents
{
}
@@ -2546,6 +2360,93 @@ namespace Vanara.PInvoke.VssApi
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 functions.
public static partial class Methods
{
diff --git a/PInvoke/VssApi/vsmgmt.cs b/PInvoke/VssApi/vsmgmt.cs
index 3ab279fe..e6853f98 100644
--- a/PInvoke/VssApi/vsmgmt.cs
+++ b/PInvoke/VssApi/vsmgmt.cs
@@ -713,11 +713,6 @@ namespace Vanara.PInvoke.VssApi
/// The IVssEnumMgmtObject interface contains methods to iterate over and perform other operations on a list of enumerated objects.
///
///
- /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned
- /// IVssEnumMgmtObject when it is no longer needed. It may also need to call IUnknown::Release to release temporary
- /// objects (such as strings) returned during enumeration.
- ///
- ///
/// The IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasForSnapshot, IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasForVolume,
/// IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasOnVolume, and
/// IVssDifferentialSoftwareSnapshotMgmt::QueryVolumesSupportedForDiffAreas methods return an IVssEnumMgmtObject object.
diff --git a/PInvoke/VssApi/vsprov.cs b/PInvoke/VssApi/vsprov.cs
index 4b067ab7..492ac6eb 100644
--- a/PInvoke/VssApi/vsprov.cs
+++ b/PInvoke/VssApi/vsprov.cs
@@ -927,10 +927,8 @@ namespace Vanara.PInvoke.VssApi
///
///
/// In the case of persistent shadow copies, the requester deletes the shadow copy when it is no longer needed. In the case of
- /// nonpersistent auto-release shadow copies, the VSS service deletes the shadow copy when the requester calls IUnknown::Release on
- /// the IVssBackupComponents object. In the case of nonpersistent non-auto-release shadow copies, the VSS service deletes the shadow
- /// copy when the computer is restarted. In all cases, the VSS service calls the provider's OnLunEmpty method as needed for
- /// each shadow copy LUN.
+ /// nonpersistent non-auto-release shadow copies, the VSS service deletes the shadow copy when the computer is restarted. In all
+ /// cases, the VSS service calls the provider's OnLunEmpty method as needed for each shadow copy LUN.
///
///
/// Note that OnLunEmpty is called on a best effort basis. VSS invokes the method only when the LUN is guaranteed to be
@@ -1072,8 +1070,7 @@ namespace Vanara.PInvoke.VssApi
///
///
/// A pointer to a location that will receive an IVssAsync interface pointer that can be used to retrieve the status of the
- /// resynchronization operation. When the operation is complete, the caller must release the interface pointer by calling the
- /// IUnknown::Release method.
+ /// resynchronization operation.
///
///
/// This method can return one of these values.
@@ -2149,7 +2146,7 @@ namespace Vanara.PInvoke.VssApi
///
///
/// Pointer to a location that will receive an IVssAsync interface pointer that can be used to retrieve the status of the revert
- /// operation. When the operation is complete, the caller must release the interface pointer by calling the IUnknown::Release method.
+ /// operation.
///
///
/// The following are the valid return codes for this method.
diff --git a/PInvoke/VssApi/vss.cs b/PInvoke/VssApi/vss.cs
index a7247d75..8e62ebde 100644
--- a/PInvoke/VssApi/vss.cs
+++ b/PInvoke/VssApi/vss.cs
@@ -1583,10 +1583,6 @@ namespace Vanara.PInvoke.VssApi
/// The IVssAsync interface permits an application to monitor and control an asynchronous operation by waiting on its completion,
/// querying its status, or canceling it.
///
- ///
- /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned IVssAsync
- /// interface when it is no longer needed.
- ///
/// The following methods return an IVssAsync interface:
///
/// -
@@ -1783,11 +1779,6 @@ namespace Vanara.PInvoke.VssApi
///
/// The IVssEnumObject interface contains methods to iterate over and perform other operations on a list of enumerated objects.
///
- ///
- /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned
- /// IVssEnumObject when it is no longer needed. It may also need to call IUnknown::Release to release temporary objects
- /// (such as strings) returned during enumeration.
- ///
/// The IVssBackupComponents::Query method returns an IVssEnumObject object.
///
// https://docs.microsoft.com/en-us/windows/win32/api/vss/nn-vss-ivssenumobject
@@ -1889,7 +1880,7 @@ namespace Vanara.PInvoke.VssApi
/// enumerator object.
///
///
- /// Doubly indirect pointer to an IVssEnumObject enumerator object. Set the value of this parameter to NULL before calling
+ /// An IVssEnumObject enumerator object. Set the value of this parameter to NULL before calling
/// this method.
///
///
diff --git a/PInvoke/VssApi/vswriter.cs b/PInvoke/VssApi/vswriter.cs
index 9429ac6d..09805f93 100644
--- a/PInvoke/VssApi/vswriter.cs
+++ b/PInvoke/VssApi/vswriter.cs
@@ -1,5 +1,4 @@
using System;
-using System.Collections;
using System.Collections.Generic;
using System.Runtime.InteropServices;
@@ -719,8 +718,8 @@ namespace Vanara.PInvoke.VssApi
///
///
- /// The IVssComponent interface is a C++ (not COM) interface containing methods for examining and modifying information about
- /// components contained in a requester's Backup Components Document.
+ /// The IVssComponent interface contains methods for examining and modifying information about components contained in a
+ /// requester's Backup Components Document.
///
///
/// IVssComponent objects can be obtained only for those components that have been explicitly added to the Backup Components
@@ -1732,7 +1731,7 @@ namespace Vanara.PInvoke.VssApi
// wszFilespec, [in] bool bRecursive, [in] LPCWSTR wszAlternateLocation, [in] DWORD dwBackupTypeMask );
void AddFilesToFileGroup([MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, [MarshalAs(UnmanagedType.LPWStr)] string wszGroupName,
[MarshalAs(UnmanagedType.LPWStr)] string wszPath, [MarshalAs(UnmanagedType.LPWStr)] string wszFilespec, bool bRecursive,
- [MarshalAs(UnmanagedType.LPWStr)] string wszAlternateLocation,
+ [MarshalAs(UnmanagedType.LPWStr)] string wszAlternateLocation,
VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED);
/// Specifies how an express writer's data is to be restored.
@@ -1853,8 +1852,8 @@ namespace Vanara.PInvoke.VssApi
///
///
- /// The IVssCreateWriterMetadata interface is a C++ (not COM) interface containing methods to construct the Writer Metadata
- /// Document in response to an Identify event. It is used only in the CVssWriter::OnIdentify method.
+ /// The IVssCreateWriterMetadata interface contains methods to construct the Writer Metadata Document in response to an Identify
+ /// event. It is used only in the CVssWriter::OnIdentify method.
///
/// The addition and specification of components by a writer is managed through this interface.
///
@@ -2515,8 +2514,8 @@ namespace Vanara.PInvoke.VssApi
///
///
- /// The IVssCreateWriterMetadataEx interface is a C++ (not COM) interface that defines a method to report any file sets that will
- /// be explicitly excluded when a shadow copy is created. This interface is used only in the CVssWriterEx::OnIdentifyEx method.
+ /// The IVssCreateWriterMetadataEx interface defines a method to report any file sets that will be explicitly excluded when a
+ /// shadow copy is created. This interface is used only in the CVssWriterEx::OnIdentifyEx method.
///
/// The IVssCreateWriterMetadataEx interface inherits from the IVssCreateWriterMetadata interface and IUnknown.
///
@@ -2568,9 +2567,6 @@ namespace Vanara.PInvoke.VssApi
/// This method is not a substitute for the IVssCreateWriterMetadata::AddExcludeFiles method. Writers should continue to use the
/// AddExcludeFiles method to report which file sets are excluded from backup.
///
- ///
- /// The caller is responsible for calling the IUnknown::Release method to release the resources of the returned IVssWMFiledesc object.
- ///
///
// https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadataex-addexcludefilesfromsnapshot
// HRESULT AddExcludeFilesFromSnapshot( [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive );
@@ -2652,9 +2648,9 @@ namespace Vanara.PInvoke.VssApi
///
///
- /// The IVssWMDependency is a C++ (not COM) interface returned by the IVssWMComponent interface and used by applications when
- /// backing up or restoring a component that has an explicit writer-component dependency on a component managed by another writer.
- /// (Dependencies must be between writers, not within writers.)
+ /// The IVssWMDependency is returned by the IVssWMComponent interface and used by applications when backing up or restoring a
+ /// component that has an explicit writer-component dependency on a component managed by another writer. (Dependencies must be between
+ /// writers, not within writers.)
///
///
/// IVssWMDependency is used to determine the writer ID, logical path, and component name of components that must be restored or
@@ -2664,10 +2660,6 @@ namespace Vanara.PInvoke.VssApi
/// Dependencies are created by writers while handling Identify events (CVssWriter::OnIdentify) using the
/// IVssCreateWriterMetadata::AddComponentDependency method.
///
- ///
- /// Calling applications are responsible for calling IUnknown::Release to release resources held by a returned IVssWMDependency
- /// object when it is no longer needed.
- ///
/// The IVssWMComponent::GetDependency method returns an IVssWMDependency interface.
///
/// Note that a dependency does not indicate an order of preference between the component with the documented dependencies and the
@@ -2759,12 +2751,8 @@ namespace Vanara.PInvoke.VssApi
///
///
- /// The IVssWMFiledesc interface is a C++ (not COM) interface returned to a calling application by a number of query methods. It
- /// provides detailed information about a file or set of files (a file set).
- ///
- ///
- /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned
- /// IVssWMFiledesc interface when it is no longer needed.
+ /// The IVssWMFiledesc interface is returned to a calling application by a number of query methods. It provides detailed
+ /// information about a file or set of files (a file set).
///
/// The following methods return an IVssWMFiledesc interface:
///
@@ -2921,8 +2909,8 @@ namespace Vanara.PInvoke.VssApi
///
///
- /// The IVssWriterComponents interface is a C++ (not COM) interface that contains methods used to obtain and modify component
- /// information (in the form of IVssComponent objects) associated with a given writer but stored in a requester's Backup Components Document.
+ /// The IVssWriterComponents interface contains methods used to obtain and modify component information (in the form of
+ /// IVssComponent objects) associated with a given writer but stored in a requester's Backup Components Document.
///
///
/// The CVssWriter base class is responsible for passing an instance of the IVssWriterComponents interface to the following event handlers:
@@ -3265,9 +3253,6 @@ namespace Vanara.PInvoke.VssApi
/// The caller should free the memory held by the pbstrLogicalPath and pbstrComponentName parameters by calling SysFreeString.
public struct VssRestoreSubcomponent
{
- /// Reserved for future use.
- public bool Repair;
-
/// Pointer to a string containing the name of the subcomponent. The string cannot be empty.
public string ComponentName;
@@ -3275,5 +3260,8 @@ namespace Vanara.PInvoke.VssApi
/// Pointer to a string containing the logical path of the subcomponent. The logical path cannot be empty when working with subcomponents.
///
public string LogicalPath;
+
+ /// Reserved for future use.
+ public bool Repair;
}
}
\ No newline at end of file