CVssWriter::OnBackupComplete method (vswriter.h)

The OnBackupComplete method is called by a writer following a BackupComplete event. It is used to perform operations considered necessary following a backup. These operations cannot, however, modify the Backup Components Document.

OnBackupComplete is a virtual method. It is implemented by the CVssWriter base class, but can be overridden by derived classes.

Syntax

bool OnBackupComplete(
  [in] IVssWriterComponents *pComponent
);

Parameters

[in] pComponent

A pointer to an IVssWriterComponents object passed in by VSS to provide the method with access to the writer's component information. The value of this parameter may be NULL if the requester does not support components (if CVssWriter::AreComponentsSelected returns false).

Return value

As implemented by the base class, OnBackupComplete always returns true.

Any other implementation of this method should return true except in the case of a fatal error. If a fatal error occurs, the method must call the CVssWriter::SetWriterFailure method to provide a description of the failure before returning false. If a nonfatal error occurs, the method should still call SetWriterFailure but return true. If the error is caused by a transient problem, the method should specify VSS_E_WRITERERROR_RETRYABLE in the call to SetWriterFailure.

In all cases when a failure occurs, the method should write an event to the event log to report the exact reason for the failure.

Remarks

The default implementation of this method by CVssWriter base class returns true without performing any other operation.

If special operations are to be performed by the writer at the end of a backup, the default implementation can be overridden.

With the generation of a BackupComplete event, a requester's Backup Components Document becomes a read-only document. Therefore, attempts to modify the document through the interface (for instance, calling IVssComponent::SetBackupMetadata) will fail in user implementations of OnBackupComplete.

A successful backup application will generate a BackupComplete event when all data has been saved to backup media.

However, there is no guarantee of the writer receiving a BackupComplete event notification, because these require the backup application to either successfully complete the backup or fail gracefully.

A BackupComplete event could fail to be generated should the backup application be terminated by the system or manually prior to the completion of the backup (for instance, if the backup operation hung and had to be shut down).

A writer should maintain state information so that it can track whether a BackupComplete event was sent for a given shadow copy set.

This information can be used by a writer's BackupShutdown event handler (CVssWriter::OnBackupShutdown), which will be called when a backup application actually terminates and its IVssBackupComponents is released, to perform cleanup operations should there be no call to OnBackupComplete.

Writers should never throw an exception from this method or any other CVssWriter(Ex)::OnXxx callback method.

If this method calls the CVssWriterEx2::GetSessionId, CVssWriter::SetWriterFailure, or CVssWriterEx2::SetWriterFailureEx method, it must do so in the same thread that called this method. For more information, see Writer Event Handling.

Requirements

See also

CVssWriter

CVssWriter::SetWriterFailure

IVssBackupComponents

IVssWriterComponents