IBackgroundCopyJob::GetError method

Article
09/23/2021

Retrieves the error interface after an error occurs.

Delivery Optimization generates an error object when the state of the job is BG_JOB_STATE_ERROR or BG_JOB_STATE_TRANSIENT_ERROR. The service does not create an error object when a call to an IBackgroundCopyXXXX interface method fails. The error object is available until Delivery Optimization begins transferring data (the state of the job changes to BG_JOB_STATE_TRANSFERRING) for the job or until your application exits.

Syntax

HRESULT GetError(
  [out] IBackgroundCopyError **ppError
);

Parameters

ppError [out]: Error interface that provides the error code, a description of the error, and the context in which the error occurred. This parameter also identifies the file being transferred at the time the error occurred. Release ppError when done.

Return value

This method returns the following HRESULT values, as well as others.

Return code	Description
S_OK	Successfully generated the error object.
DO_E_ERROR_INFORMATION_UNAVAILABLE	The error interface is available only after an error occurs (BG_JOB_STATE_ERROR or BG_JOB_STATE_TRANSIENT_ERROR) and before Delivery Optimization begins transferring data (BG_JOB_STATE_TRANSFERRING).

Remarks

The job is placed in an error state on fatal errors. Use one of the following options to determine if the job is in error:

To poll for the state of the job, call the IBackgroundCopyJob::GetState method. The job is in error if the state is BG_JOB_STATE_ERROR.
To receive notification when an error occurs, implement the IBackgroundCopyCallback interface (specifically, the JobError method). Then, call the IBackgroundCopyJob::SetNotifyInterface method to register the callback and the IBackgroundCopyJob::SetNotifyFlags method to set the BG_NOTIFY_JOB_ERROR flag.

The IBackgroundCopyError interface contains information that you use to determine the cause of the error and if the transfer process can proceed. After you determine the cause of the error, perform one of the following options:

To cancel the job, call the IBackgroundCopyJob::Cancel method.
To save those files that transferred successfully before the error occurred, call the IBackgroundCopyJob::Complete method.
To finish processing the job, fix the problem, and then call the IBackgroundCopyJob::Resume method.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1709 [desktop apps only]
Minimum supported server	Windows Server, version 1709 [desktop apps only]
Header	Deliveryoptimization.h
IDL	DeliveryOptimization.idl
Library	Dosvc.lib
DLL	Dosvc.dll
IID	IID_IBackgroundCopyJob is defined as 37668D37-507E-4160-9316-26306D150B12