IVssExamineWriterMetadataEx::GetIdentityEx method (vsbackup.h)
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 |
---|---|
|
Successfully returned the identity information. |
|
One of the parameter values is not valid. |
|
The caller is out of memory or other system resources. |
|
The XML document is not valid. Check the event log for details. For more information, see Event and Error Handling Under VSS. |
|
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 |