CVssWriter::OnPrepareBackup method (vswriter.h)

The OnPrepareBackup method is called by a writer following a PrepareForBackup event. This method is used to configure a writer's state and its components in preparation for a backup operation.

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

Syntax

bool OnPrepareBackup(
  [in] IVssWriterComponents *pComponent
);

Parameters

[in] pComponent

Pointer to an instantiation of an IVssWriterComponents object containing the contents of the Writer Metadata Document. 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, OnPrepareBackup always returns true.

Any other implementation of this method must 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 the CVssWriter base class returns true without performing any other operation.

OnPrepareBackup provides a writer an opportunity to more finely select what will be backed up.

Handling the PrepareForBackup event is the last opportunity for a writer to get access to metadata contained in the Backup Components Document prior to the shadow copy's creation.

Therefore, OnPrepareBackup provides an opportunity for the writer to make any final additions or updates to stored component information (using the IVssComponent interface). In particular, writer-specific metadata can be updated by IVssComponent::SetBackupMetadata or IVssComponent::SetRestoreMetadata.

In addition, while handling the PrepareForSnapshot event provides another opportunity in the life cycle of a VSS backup operation to perform time-consuming operations (such as synchronizing data across multiple sites), OnPrepareBackup provides a chance for the writer to start such an operation asynchronously. Tasks like these must be completed prior to the return of CVssWriter::OnPrepareSnapshot.

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

A requester generates a PrepareForBackup event, triggering a call to OnPrepareBackup, by calling IVssBackupComponents::PrepareForBackup.

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::OnPostSnapshot

CVssWriter::OnPreRestore

CVssWriter::SetWriterFailure

IVssWriterComponents