CVssWriter::Initialize method

Initializes a CVssWriter object and allows a writer application to interact with VSS.

Initialize is a public method implemented by the CVssWriter base class.

Syntax

HRESULT Initialize(
  VSS_ID                     WriterId,
  LPCWSTR                    wszWriterName,
  VSS_USAGE_TYPE             ut,
  VSS_SOURCE_TYPE            st,
  VSS_APPLICATION_LEVEL      nLevel,
  DWORD                      dwTimeoutFreeze,
  VSS_ALTERNATE_WRITER_STATE aws,
  bool                       bIOThrottlingOnly,
  LPCWSTR                    wszWriterInstanceName
);

Parameters

WriterId

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

wszWriterName

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

ut

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

st

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

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.

dwTimeoutFreeze

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

The default value for this parameter is 60000.

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.

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.

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 details, see the following Remarks section.

Windows Server 2003 and Windows XP:  Before Windows Server 2003 with SP1, this parameter is reserved for system use, and the caller should not override the default value.

Return Value

The following are the valid return codes for this method.

Value Meaning
S_OK
Successfully initialized the writer object.
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

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

   
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

See Also

CVssWriter

CVssWriter::OnAbort

VSS_ALTERNATE_WRITER_STATE

VSS_APPLICATION_LEVEL

VSS_ID

VSS_SOURCE_TYPE

VSS_USAGE_TYPE