DownloadOperation class

Applies to Windows and Windows Phone

Performs an asynchronous download operation. The Background Transfer sample demonstrates this functionality. For an overview of Background Transfer capabilities, see Transferring data in the background. Download the Background Transfer sample for examples in JavaScript, C#, and C++.

Syntax


var downloadOperation = promise.operation;

Attributes

[MarshalingBehavior(Agile)]
[Version(0x06020000)]

Members

The DownloadOperation class has these types of members:

Methods

The DownloadOperation class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
AttachAsync 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.
GetResponseInformation Gets the response information.
GetResultStreamAt Gets the partially downloaded response at the specified position.
Pause Pauses a download operation.
Resume Resumes a paused download operation.
StartAsync Starts an asynchronous download operation.

 

Properties

The DownloadOperation class has these properties.

PropertyAccess typeDescription

CostPolicy

Read/writeGets and sets the cost policy for the download.

Group

Read-onlyGets a string value indicating the group the transfer belongs to.

Guid

Read-onlyThis is a unique identifier for a specific download operation. A GUID associated to a download operation will not change for the duration of the download.

Method

Read-onlyGets the method to use for the download.

Priority

Read/writeGets or sets the transfer priority of this download operation when within a BackgroundTransferGroup. Possible values are defined by BackgroundTransferPriority.

Progress

Read-onlyGets the current progress of the upload operation.

RequestedUri

Read-onlyGets the URI from which to download the file.

ResultFile

Read-onlyReturns the IStorageFile object provided by the caller when creating the DownloadOperation object using CreateDownload.

TransferGroup

Read-onlyGets the group that this download operation belongs to.

 

Remarks

After app termination, an app should enumerate all existing DownloadOperation instances at next start-up using GetCurrentDownloadsAsync. When a Windows Store app using Background Transfer is terminated, incomplete downloads will persist in the background. If the app is restarted after termination and these incomplete operations are not enumerated and re-introduced to the current session, they will go stale and continue to occupy device resources.

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.

Note  Paused or incomplete download operations can only be resumed if the server accepts range-requests.

Timeout considerations

1.) When establishing a new connection for a download over TCP/SSL, the connection attempt is aborted if not established within five minutes.

2.) After the connection has been established, an HTTP request message that has not received a response within two minutes is aborted.

Assuming there is Internet connectivity, Background Transfer will retry a download up to three times. In the event Internet connectivity is not detected, additional attempts will not be made until it is.

Debugging Guidance

Stopping a debugging session in Microsoft Visual Studio is comparable to closing your app; downloads are paused and POST uploads are terminated. Even while debugging, your app should enumerate and then pause, resume, restart, or cancel any persisted downloads.

However, if Visual Studio project updates, like changes to the app manifest, require that the app is uninstalled and re-deployed for debugging, GetCurrentDownloadsAsync cannot enumerate persisted operations created using the previous app deployment.

Examples

The following example demonstrates how to configure and begin a basic download operation, and is based on the Background Transfer sample offered in the Windows Sample Gallery.


        var download = null;
        var promise = null;

        function DownloadFile (uriString, fileName) {
            try {
                // Asynchronously create the file in the pictures folder.
                Windows.Storage.KnownFolders.picturesLibrary.createFileAsync(fileName, Windows.Storage.CreationCollisionOption.generateUniqueName).done(function (newFile) {
                    var uri = Windows.Foundation.Uri(uriString);
                    var downloader = new Windows.Networking.BackgroundTransfer.BackgroundDownloader();

                    // Create a new download operation.
                    download = downloader.createDownload(uri, newFile);

                    // Start the download and persist the promise to be able to cancel the download.
                    promise = download.startAsync().then(complete, error, progress);
                }, error);
            } catch (err) {
                displayException(err);
            }
        };

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

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

Capabilities

internetClient
internetClientServer
privateNetworkClientServer

See also

Quickstart: Download a file
Background Transfer sample

 

 

Show:
© 2014 Microsoft