CVssWriterEx::OnIdentifyEx method (vswriter.h)

Article
07/12/2022

Returns a pointer to an IVssCreateWriterMetadataEx object.

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

Syntax

bool OnIdentifyEx(
  [in] IVssCreateWriterMetadataEx *pMetadata
);

Parameters

[in] pMetadata

A pointer to an IVssCreateWriterMetadataEx object.

Return value

As implemented by the base class, OnIdentifyEx 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 OnIdentifyEx method is identical to the OnIdentify method, except that it returns an IVssCreateWriterMetadataEx interface pointer instead of an IVssCreateWriterMetadata interface pointer in the pMetadata parameter. A writer can override OnIdentify or OnIdentifyEx, but not both.

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 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 that is generated by another application, a writer calls OnIdentifyEx to create a Writer Metadata Document that contains information about the components it manages using the IVssCreateWriterMetadataEx 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, OnIdentifyEx is typically called 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 by itself is not part of the sequence of events that make up a backup or restore sequence, and the VSS service does not prevent Identify events from being generated, even while a backup or restore sequence is in progress. For example, VSS management applications use the Identify event to determine and display the state of the writers on the system.

For this reason, writers should never use their implementation of OnIdentifyEx in any of the following ways:

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

For more information about writer interactions with events, see Writer Event Handling.

During the PrepareForBackup, PrepareForSnapshot, and PostSnapshot events, a writer can use the GetIdentifyInformation method to get the metadata that the writer's OnIdentifyEx method previously reported.

The life cycle of the IVssCreateWriterMetadataEx object that the pMetadata parameter points to is managed by the VSS infrastructure.

Requirements

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