Export (0) Print
Expand All

IVssBackupComponents::GetWriterStatus method

The GetWriterStatus method returns the status of the specified writer.

Syntax


HRESULT GetWriterStatus(
  [in]   UINT iWriter,
  [out]  VSS_ID *pidInstance,
  [out]  VSS_ID *pidWriter,
  [out]  BSTR *pbstrWriter,
  [out]  VSS_WRITER_STATE *pState,
  [out]  HRESULT *pHrResultFailure
);

Parameters

iWriter [in]

Index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 inclusive, where n is the total number of writers on the current system. The value of n is returned by IVssBackupComponents::GetWriterStatusCount.

pidInstance [out]

The address of a caller-allocated variable that receives the instance identifier of the writer.

pidWriter [out]

The address of a caller-allocated variable that receives the identifier for the writer class.

pbstrWriter [out]

The address of a caller-allocated variable that receives a string containing the name of the specified writer.

pState [out]

The address of a caller-allocated variable that receives a VSS_WRITER_STATE enumeration value.

pHrResultFailure [out]

The address of a caller-allocated variable that receives the HRESULT failure code that was returned by the writer.

The following are the supported values for pHrResultFailure.

ValueMeaning
S_OK

The writer was successful.

VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT

The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component.

VSS_E_WRITERERROR_OUTOFRESOURCES

The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times.

VSS_E_WRITERERROR_TIMEOUT

The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times.

VSS_E_WRITERERROR_RETRYABLE

The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process was restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times.

VSS_E_WRITERERROR_NONRETRYABLE

The writer operation failed because of an error that might recur if another shadow copy is created. For more information, see Event and Error Handling Under VSS.

VSS_E_WRITER_NOT_RESPONDING

The writer is not responding.

VSS_E_WRITER_STATUS_NOT_AVAILABLE

The writer status is not available for one or more writers. A writer may have reached the maximum number of available backup and restore sessions.

Windows Vista, Windows Server 2003, and Windows XP:  This value is not supported.

 

Return value

The following are the valid return codes for this method.

ValueMeaning
S_OK

Successfully returned the status of the specified writer. Note that the value of the pHrWriterFailure parameter must be checked to verify that the writer was successful. The writer failure codes can be among those listed in VsWriter.h and in Writer Errors and Vetoes.

E_INVALIDARG

One of the parameter values is not valid.

E_OUTOFMEMORY

The caller is out of memory or other system resources.

VSS_E_BAD_STATE

The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.

VSS_E_OBJECT_NOT_FOUND

The specified writer does not exist.

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

A requester must call the asynchronous operation IVssBackupComponents::GatherWriterStatus and wait for it to complete prior to calling GetWriterStatus.

When the caller has finished accessing the status information returned by this method, it should call SysFreeString to free the memory held by the pbstrWriter parameter.

The VSS_E_WRITERERROR_XXX values returned in the pHrResultFailure parameter are generated by writers. VSS_E_WRITER_NOT_RESPONDING and VSS_E_WRITER_STATUS_NOT_AVAILABLE are generated by VSS.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

VsBackup.h (include VsBackup.h, Vss.h, or VsWriter.h)

Library

VssApi.lib

See also

IVssBackupComponents
IVssBackupComponents::GetWriterStatusCount
IVssBackupComponents::GatherWriterStatus

 

 

Community Additions

ADD
Show:
© 2014 Microsoft