Edit

IVssExamineWriterMetadataEx::GetIdentityEx method (vsbackup.h)

  • Article

The GetIdentityEx method obtains the writer instance name and other basic information about a specific writer instance.

Syntax

HRESULT GetIdentityEx(
  [out] VSS_ID          *pidInstance,
  [out] VSS_ID          *pidWriter,
  [out] BSTR            *pbstrWriterName,
  [out] BSTR            *pbstrInstanceName,
  [out] VSS_USAGE_TYPE  *pUsage,
  [out] VSS_SOURCE_TYPE *pSource
);

Parameters

[out] pidInstance

Globally unique identifier (GUID) of the writer instance.

[out] pidWriter

GUID of the writer class.

[out] pbstrWriterName

Pointer to a string specifying the name of the writer.

[out] pbstrInstanceName

Pointer to a string specifying the writer instance name.

[out] pUsage

Pointer to a VSS_USAGE_TYPE enumeration value indicating how the data managed by the writer is used on the host system.

[out] pSource

Pointer to a VSS_SOURCE_TYPE enumeration value indicating the type of data managed by the writer.

Return value

The following are the valid return codes for this method.

Value Meaning
S_OK
 Successfully returned the identity information.
E_INVALIDARG
 One of the parameter values is not valid.
E_OUTOFMEMORY
 The caller is out of memory or other system resources.
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.

Remarks

This method is identical to the IVssExamineWriterMetadata::GetIdentity method except for the pbstrInstanceName parameter.

The pbstrInstanceName parameter is the writer instance name that was specified during writer initialization by CVssWriter::Initialize.

The writer instance name is useful for writers that support running multiple writer instances with the same writer class ID on a single computer. The writer instance name can be used to identify the specific instance. Therefore, the writer must make the instance name unique within the writer class. Also, the writer instance name is expected to persist between backup and restore, and it is used by VSS to correctly restore multiple-instance writers.

The caller must free the memory held by the pbstrWriterName and pbstrInstanceName parameters by calling SysFreeString.

An IVssExamineWriterMetadataEx interface might be from stored writer state information (created by a call to CreateVssExamineWriterMetadata). If this is the case, then the following are true:

  • pidInstance may not mean anything in terms of live writers.
  • If pidWriter does not match the writer class of any live writer, a requester should not use that writer's components.

Requirements

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

See also

CVssWriter::Initialize

IVssExamineWriterMetadataEx