CVssWriterEx::InitializeEx method (vswriter.h)

Article
10/13/2021

Initializes a CVssWriterEx object and allows a writer application to interact with VSS. Unlike the Initialize method, the InitializeEx method allows the caller to specify writer version information.

InitializeEx is a public method implemented by the CVssWriterEx base class.

Writers must call Initialize or InitializeEx, but not both.

Syntax

HRESULT InitializeEx(
  [in] VSS_ID                     WriterId,
  [in] LPCWSTR                    wszWriterName,
  [in] DWORD                      dwMajorVersion,
  [in] DWORD                      dwMinorVersion,
  [in] VSS_USAGE_TYPE             ut,
  [in] VSS_SOURCE_TYPE            st,
  [in] VSS_APPLICATION_LEVEL      nLevel,
  [in] DWORD                      dwTimeoutFreeze,
  [in] VSS_ALTERNATE_WRITER_STATE aws,
  [in] bool                       bIOThrottlingOnly,
  [in] LPCWSTR                    wszWriterInstanceName
);

Parameters

[in] WriterId

The globally unique identifier (GUID) of the writer class.

[in] wszWriterName

A null-terminated wide character string that contains the name of the writer. This string is not localized.

[in] dwMajorVersion

The major version of the writer application. For more information, see the Remarks section.

[in] dwMinorVersion

The minor version of the writer application. For more information, see the Remarks section.

[in] ut

A VSS_USAGE_TYPE enumeration value that indicates how the data that is managed by the writer is used on the host system.

[in] st

A VSS_SOURCE_TYPE enumeration value that indicates the type of data that is managed by the writer.

[in] nLevel

A VSS_APPLICATION_LEVEL enumeration value that indicates the application level at which the writer receives a Freeze event notification.

The default value for this parameter is VSS_APP_FRONT_END.

[in] dwTimeoutFreeze

The maximum permitted time, in milliseconds, between the writer's receipt of a Freeze event notification and its receipt of a matching Thaw event notification from VSS. After the time-out expires, the writer's OnAbort method is called automatically.

The default value for this parameter is 60000.

[in] aws

A VSS_ALTERNATE_WRITER_STATE enumeration value that indicates whether the writer has an associated alternate writer.

The default value for this parameter is VSS_AWS_NO_ALTERNATE_WRITER. The caller should not override this default value. This parameter is reserved for future use.

[in] bIOThrottlingOnly

Set this parameter to true if I/O throttling methods are enabled, or false otherwise.

The default value for this parameter is false. The caller should not override this default value. This parameter is reserved for future use.

[in] wszWriterInstanceName

A null-terminated wide character string that contains the writer instance name.

The default value for this parameter is NULL. If the writer has multiple instances and requires restore events, this parameter is required and cannot be NULL. For more information, see the following Remarks section.

Return value

The following are the valid return codes for this method.

Value	Meaning
S_OK	The writer object was successfully initialized.
S_FALSE	The writer object could not be initialized; the VSS writer infrastructure was inactive because Windows was in safe mode or was setting up.
E_ACCESSDENIED	The caller is not an administrator.
E_INVALIDARG	One of the parameter values is not valid.
E_OUTOFMEMORY	The caller is out of memory or other system resources.
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

The InitializeEx method is identical to the Initialize method except for the dwMajorVersion and dwMinorVersion parameters. If the writer uses Initialize instead of InitializeEx, the writer version will be reported as 0.0 (major version = 0, minor version = 0) by the IVssExamineWriterMetadataEx2::GetVersion method.

The dwMajorVersion and dwMinorVersion parameters are used to specify the writer major and minor version numbers according to the following VSS conventions:

If the writer has changed since Windows XP or is new for Windows Vista, it should specify 1.0 or higher for its version number.
A writer's minor version number should be incremented by one whenever a released version of the writer contains minor changes that affect the writer's interaction with requesters. For example, a correction to a file specification in a writer QFE or service pack would justify incrementing the minor version number. However, a change between beta or release candidate versions of a writer would not justify the changing of the minor version number.
A writer's major version number should be incremented by one whenever a released version of the writer contains a significant change. For example, if data that is backed up with a new version of a writer cannot be restored using the previous version of the writer, the new writer's major version number should be incremented.
Whenever the major version number is incremented, the minor version number should be reset to zero.

If a writer does not specify a version number, VSS will assign a default version number of 0.0.

VSS assigns a unique writer instance ID to each instance of a writer application. If more than one instance is present on the system at the same time (for example, if multiple SQL servers are running on a system), each writer is uniquely identified by the combination of its writer class ID and its writer instance ID.

The wszWriterInstanceName parameter allows a multi-instance writer to specify a persistent name for each writer instance as a human-readable string. This name must be unique across all instances of the writer on the system. If a writer has multiple instances and requires restore events, it must specify a non-NULL string for this parameter. VSS uses the instance name to correctly restore multi-instance writers.

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