Share via

Windows.Networking.BackgroundTransfer Namespace

  • Reference
Edit

Enables advanced download and upload transfer capabilities within an app. For an overview of Background Transfer capabilities, see Transferring data in the background. Download the Background transfer sample for a code example.

Note

Background transfer is primarily designed for long-term transfer operations for resources like video, music, and large images. For short-term operations involving transfers of smaller resources (i.e. a couple KB), the HTTP APIs are recommended. HttpClient is preferred and can be used in all languages supported by UWP apps. XHR can be used in JavaScript. IXHR2 can be used in C++.

Classes

BackgroundDownloader

Used to configure downloads prior to the actual creation of the download operation using CreateDownload. For an overview of Background Transfer capabilities, see Transferring data in the background. Download the Background transfer sample for a code example.

Note

Background Transfer is primarily designed for long-term transfer operations for resources like video, music, and large images. For short-term operations involving transfers of smaller resources (i.e. a couple KB), use the Windows.Web.Http namespace.
BackgroundTransferCompletionGroup

Represents a set of background transfer operations (DownloadOperation or UploadOperation objects) that trigger a background task once all the operations are done (if the operations completed successfully) or fail with an error.
BackgroundTransferCompletionGroupTriggerDetails

Contains information about a BackgroundTransferCompletionGroup that can be only accessed from the Run method on the IBackgroundTask.
BackgroundTransferContentPart

Represents a content part of a multi-part transfer request. Each BackgroundTransferContentPart object can represent either a single string of text content or a single file payload, but not both.
BackgroundTransferError

Used to provide errors encountered during a transfer operation.
BackgroundTransferGroup

A named group used to associate multiple download or upload operations. This class makes it easy for your app to create these groups and to complete downloads and uploads simultaneously, in serial, or based on priority.

For example, if a user decides to download and watch episodes from a popular television series, your app can prioritize the earliest episodes in the series or let the user choose which episode to download first.
BackgroundTransferRangesDownloadedEventArgs

Provides access to information about the incremental download progress event.
BackgroundUploader

Used to configure upload prior to the actual creation of the upload operation using CreateUpload. For an overview of Background Transfer capabilities, see Transferring data in the background. Download the Background transfer sample for a code example.

Note

Background Transfer is primarily designed for long-term transfer operations for resources like video, music, and large images. For short-term operations involving transfers of smaller resources (i.e. a couple KB), use the Windows.Web.Http namespace.
ContentPrefetcher

Provides properties for specifying web resources to be prefetched. Windows will use heuristics to attempt to download the specified resources in advance of your app being launched by the user.
DownloadOperation

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.
ResponseInformation

Represents data that is returned by a server response.
UnconstrainedTransferRequestResult

Represents the result a request for unconstrained transfers from a BackgroundDownloader or BackgroundUploader object.

Unconstrained transfer operations can run without the resource restrictions normally associated with background network operations while a device running on battery.
UploadOperation

Performs an asynchronous upload operation. For an overview of Background Transfer capabilities, see Transferring data in the background. Download the Background transfer sample for a code example.

Structs

BackgroundDownloadProgress

Contains status information about the download operation.
BackgroundTransferFileRange

Contains status information about the file transfer operation.
BackgroundUploadProgress

Contains status information about the upload operation.

Interfaces

IBackgroundTransferBase

Represents a background transfer operation.
IBackgroundTransferContentPartFactory

Creates a BackgroundTransferContentPart object.
IBackgroundTransferOperation

Represents a background transfer operation.
IBackgroundTransferOperationPriority

Use this interface to determine the priority of a downloads or uploads within a BackgroundTransferGroup. Possible values are defined by the BackgroundTransferPriority enumeration.

Enums

BackgroundTransferBehavior

Defines values used to indicate if downloads and uploads within a BackgroundTransferGroup run in simultaneously or in serial.
BackgroundTransferCostPolicy

Defines values used to specify whether transfers can occur on metered networks.
BackgroundTransferPriority

Indicates the priority that a BackgroundTransfer operation(download or upload) has in terms of scheduling within an app.
BackgroundTransferStatus

Defines transfer operation status values.

Remarks

On most platforms, Background Transfer will continue to transfer your files (download or upload) even when the app is suspended or when it exits. When your app starts up, you should call BackgroundDownloader.GetCurrentDownloadsAsync or BackgroundUploader.GetCurrentUploadsAsync to enumerate all of your incomplete transfers. Then call DownloadOperation.AttachAsync or UploadOperation.AttachAsync, respectively, on each one. Doing so retrieves the transfer's latest state and causes the transfers to be resumed after a system reboot. When DownloadOperation.IsRandomAccessRequired is true, the download resumes automatically after a reboot. You should call AttachAsync even in that case. If your app is running when the transfers complete (that is, when the call to AttachAsync returns), then you can do work in response. Alternatively, you can use BackgroundTransferCompletionGroup to launch a background task when the transfers complete.

On Xbox, Background Transfer only transfers your files (download or upload) while the app is in the foreground. When an app is either suspended, put into the background, or has exited, the app's background transfers are suspended. When the app runs in the foreground again, its transfers are resumed automatically.

See also