Retrieves the error interface after an error occurs.
BITS 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 BITS begins transferring data (the state of the job changes to BG_JOB_STATE_TRANSFERRING) for the job or until your application exits.
HRESULT GetError( IBackgroundCopyError **ppError );
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.
This method returns the following HRESULT values, as well as others.
||Successfully generated the error object.|
||The error interface is available only after an error occurs (BG_JOB_STATE_ERROR or BG_JOB_STATE_TRANSIENT_ERROR) and before BITS begins transferring data (BG_JOB_STATE_TRANSFERRING).|
The job is placed in an error state on fatal errors or after the no-progress-timeout period expires for transient errors (this period is retrieved from the GetNoProgressTimeout method). 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.
- 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.
To determine whether the upload, reply, or server application portion of an upload-reply job failed, call the IBackgroundCopyError::GetError method to retrieve the context in which the error occurred. The server application failed if the context is BG_ERROR_CONTEXT_REMOTE_APPLICATION. If the error is with the upload or reply, the context is BG_ERROR_CONTEXT_REMOTE_FILE. The upload failed if the BytesTotal member of the BG_JOB_REPLY_PROGRESS structure is BG_SIZE_UNKNOWN. Otherwise, the reply failed.
See the example code in the Handling Errors topic.
|Minimum supported client||Windows XP|
|Minimum supported server||Windows Server 2003|