Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

DownloadOperation.StartAsync | startAsync method

Applies to Windows and Windows Phone

Starts an asynchronous download operation.

Syntax


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

Parameters

This method has no parameters.

Return value

Type: IAsyncOperationWithProgress<DownloadOperation, DownloadOperation>

An asynchronous download operation that includes progress updates.

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

Background transfer doesn't support concurrent downloads of the same Uri. So an app can download http://example.com/myfile.wmv once, or download it again after a previous download completed. An app shouldn't start two downloads of the same Uri concurrently, since this may result in truncated files.

A download operation must be scheduled using one of the BackgroundDownloader.CreateDownload or BackgroundDownloader.CreateDownloadAsync methods before the StartAsync method is called.

Important  

Queuing up a large number of transfers on the main UI thread can result in degraded performance of your app's UI, even though the call is awaitable. If you are queuing up a large number of transfers, it is recommended that you call StartAsync on a background worker thread as in the following example.


operation = await Task.Run(() => { return myDownloadOperation.StartAsync(); });


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

Background Transfer Download sample
BackgroundTransferError.GetStatus
DownloadOperation
Handling exceptions in network apps
Quickstart: Download a file

 

 

Show:
© 2014 Microsoft