CVssWriter::OnIdentify method (vswriter.h)

Article
07/12/2022

The OnIdentify method is called by a writer following receipt of an Identify event.

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

Syntax

bool OnIdentify(
  [in] IVssCreateWriterMetadata *pMetadata
);

Parameters

[in] pMetadata

A pointer to an IVssCreateWriterMetadata object used to construct the writer's metadata.

Return value

As implemented by the base class, OnIdentify 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 should return false.

In all cases when a failure occurs, including nonfatal errors, the method should write a detailed entry 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.

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

Writers should never call the CVssWriter::SetWriterFailure method from the OnIdentify or CVssWriterEx::OnIdentifyEx method.

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

In response to an Identify event generated by another application, a writer uses the OnIdentify handler to create a Writer Metadata Document containing information about the components it manages using the IVssCreateWriterMetadata interface.

The application that generated the Identify event then retrieves the Writer Metadata Document and examines the writer's component information using the IVssExamineWriterMetadata interface.

An Identify event is required before the events that make up a backup or restore sequence. Therefore, OnIdentify is perhaps most typically invoked to handle an Identify event in response to a requester's call to IVssBackupComponents::GatherWriterMetadata as part of a backup or restore operation.

However, an Identify event is not itself part of the sequence of events that makes up a backup or restore and the VSS service does not prevent its generation, even while a backup or restore sequence is in progress. For instance, VSS management applications use the Identify event to determine and display the state of the writers on the system.

This being the case, writers should never use their implementation of OnIdentify in the following ways:

As the beginning of their handling of a backup or restore
To set or maintain information about the writer's state

See Writer Event Handling for more information on writer interactions with events.

The life cycle of the IVssCreateWriterMetadata object passed into OnIdentify is managed by the VSS infrastructure.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	vswriter.h (include Vss.h, VsWriter.h)
Library	VssApi.lib