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