MICROSOFT_PRESS_EBOOK_PROGRAMMING_WINDOWS_8_APPS_WITH_HTML_CSS_AND_JAVASCRIPT_PDF

Starting a download transfer happens as follows. First create a StorageFile to receive the data
(though this is not required as we’ll see later in this section). Then create a DownloadOperation object
for the transfer using BackgroundDownloader.createDownload, at which point you can set its method,
costPolicy, and group properties to override the defaults supplied by the Background-Downloader. The
method is a string that identifies the type transfer being used (normally GET for HTTP or RETR for FTP).
We’ll come back to the other two properties later in the “Setting Cost Policy” and “Grouping Multiple
Transfers” sections.
Once the operation is configured as needed, the last step is to call its startAsync method with your
completed, error, and progress handlers: 72
// Asynchronously create the file in the pictures folder (capability declaration required).
Windows.Storage.KnownFolders.picturesLibrary.createFileAsync(fileName,
Windows.Storage.CreationCollisionOption.generateUniqueName)
.done(function (newFile) {
// Assume uriString is the text URI of the file to download
var uri = Windows.Foundation.Uri(uriString);
var downloader = new Windows.Networking.BackgroundTransfer.BackgroundDownloader();
// Create a new download operation.
var download = downloader.createDownload(uri, newFile);
}
// Start the download
download.startAsync().then(complete, error, progress);
While the operation underway, the following properties provide additional information on the
transfer:
• requestedUri and resultFile The same as those passed to createDownload.
• guid A unique identifier assigned to the operation.
• progress A BackgroundDownloadProgress structure with bytesReceived,
total-BytesToReceive, hasResponseChanged (a Boolean, see the getResponseInformation
method below), hasRestarted (a Boolean set to true if the download had to be restarted), and
status (a BackgroundTransferStatus value: idle, running, pausedByApplication,
pausedCostedNetwork, pausedNoNetwork, canceled, error, and completed).
A few methods of DownloadOperation can also be used with the transfer:
• pause and resume Control the download in progress. We’ll talk more of these in the “Suspend,
Resume, and Restart with Background Transfers” section below.
• getResponseInformation Returns a ResponseInformation object with properties named
headers (a collection of response headers from the server), actualUri, isResumable, and
72 The code in the sample has more structure than shown here. It defines its own DownloadOperation class that
unfortunately has the same name as the WinRT class, so I’m electing to omit mention of it.
645