DownloadOperation.AttachAsync | attachAsync method

Applies to Windows and Windows Phone

Returns an asynchronous operation that can be used to monitor progress and completion of the attached download. Calling this method allows an app to attach download operations that were started in a previous app instance.

Syntax


downloadOperation.attachAsync().done( /* Your success and error handlers */ );

Parameters

This method has no parameters.

Return value

Type: IAsyncOperationWithProgress<DownloadOperation, DownloadOperation>

Download operation with callback.

Exceptions

A number of errors can cause exceptions to occur when calling this method. You must write code to handle exceptions when you call this method. Exceptions can result from parameter validation errors, name resolution failures, and network errors. Exceptions from network errors (loss of connectivity, connection failures, and other HTTP errors, for example) can happen at any time. These errors result in exceptions being thrown. If not handled by your app, an exception can cause your entire app to be terminated by the runtime.

An app can use the HRESULT from the exception to determine the error that caused the exception. An app can then decide how to handle the exception based on the error code. The BackgroundTransferError.GetStatus method can convert most HRESULT values returned to a WebErrorStatus enumeration value. Most of the WebErrorStatus enumeration values correspond to an error returned by the native HTTP or FTP client operation. An app can filter on specific WebErrorStatus enumeration values to modify app behavior depending on the cause of the exception. Some HRESULT values when calling this method cannot be converted to a WebErrorStatus enumeration value.

For information on network exceptions, see Handling exceptions in network apps.

For a list of common errors that result in exceptions, see the Error Codes section below.

If the method fails, the exception can be one of following common exceptions.

ExceptionCondition
COMException

Thrown when a feature-specific HRESULT is returned from a method call.

This is the most common exception that is thrown by networking methods. An app should use the HRESULT from the exception to determine the cause of the error. For more information on specific errors, see the Error Codes section below.

AccessDeniedException

Thrown when access is denied to a resource or feature. This exception occurs when an app doesn't have the required network capabilities set in the app manifest for the network operation requested.

InvalidArgumentException

Thrown when one of the arguments that are provided to a method is not valid.

If user-supplied input caused this exception, an app could inform the user and request new input.

ObjectDisposedException

Thrown when an operation is performed on a disposed object.

OutOfMemoryException

Thrown when insufficient memory is available to complete the operation.

Error codes

An app can use the HRESULT from an exception to learn more detailed information on the error that caused the exception. Possible values for the HRESULT are listed in the Winerror.h header file.

The BackgroundTransferError.GetStatus method can convert most HRESULT values returned to a WebErrorStatus enumeration value. Most of the WebErrorStatus enumeration values correspond to an error returned by the native HTTP or FTP client operation.

The most common errors that can cause exceptions are below in numeric order based on the HRESULT value. Most of these errors correspond with a WebErrorStatus enumeration value that would normally be used by an app.

Some HRESULT values when calling this method cannot be converted to a WebErrorStatus enumeration value.

Name/valueMeaning
ERROR_INVALID_NAME
123L

The syntax used in the uri parameter is incorrect. This error can occur using C++ since the uri is passed as a string. (a uri of http:///, for example).

If user-supplied input caused this exception, an app could inform the user and request new input or parse the user input to eliminate the error.

E_ILLEGAL_METHOD_CALL
0x8000000EL

A method was called at an unexpected time. This error occurs if the uri parameter contains a protocol scheme other than http://, https://, or ftp://.

If user-supplied input caused this exception, an app could inform the user and request new input or parse the user input to eliminate the error.

RO_E_CLOSED
0x80000013L

The object has been closed. This error occurs if the DownloadOperation has been disposed.

E_INVALIDARG
0x80070057L

The uri parameter was a null reference (Nothing in Visual Basic).

WININET_E_NAME_NOT_RESOLVED
0x80072EE7L

The server name or address specified in the uri parameter could not be resolved.

If user-supplied input caused this exception, an app could inform the user and request new input and retry the operation.

WININET_E_CANNOT_CONNECT
0x80072EFDL

A connection with the server specified in the uri parameter could not be established.

If this error occurs , an app might retry the operation. A common approach is to retry a certain number of times with an increasing back-off interval between retries.

If the operation fails, your app may need to plan to continue without network connectivity using previously cached data.

WININET_E_CONNECTION_ABORTED
0x80072EFELL

The connection with the server was terminated abnormally.

If this error occurs , an app might retry the operation. A common approach is to retry a certain number of times with an increasing back-off interval between retries.

If the operation fails, your app may need to plan to continue without network connectivity using previously cached data.

WININET_E_CONNECTION_RESET
0x80072EFFL

The connection with the server was reset.

If this error occurs , an app might retry the operation again. A common approach is to retry a certain number of times with an increasing back-off interval between retries.

INET_E_RESOURCE_NOT_FOUND
0x800C0005L

The system cannot locate the resource specified in the uri parameter.

If user-supplied input caused this exception, an app could inform the user and request new input and retry the operation.

INET_E_REDIRECT_FAILED
0x800C0014L

A redirection problem occurred.

E_FAIL
0x80004005L

An unspecified error occurred. This can result if the download file is set to a drive that has insufficient space.

Remarks

While, this method can be called from multiple app instances, developers should not attach callbacks from the primary app instance in a background task. This will cause BackgroundTransferHost.exe to hang.

Examples



        function AttachDownload (loadedDownload) {
            try {
                download = loadedDownload;
                promise = download.attachAsync().then(complete, error, progress);
            } catch (err) {
                displayException(err);
            }
        };

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Namespace

Windows.Networking.BackgroundTransfer
Windows::Networking::BackgroundTransfer [C++]

Metadata

Windows.winmd

See also

DownloadOperation

 

 

Show:
© 2014 Microsoft