Background file transfers for Windows Phone 8

Article
05/20/2016

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

With Windows Phone OS 7.1, applications are able to queue up one or more file uploads or downloads over HTTP that will be executed in the background, even when the application is no longer running in the foreground. The APIs used for initiating file transfers should be used to query the status existing transfers and provide progress indicators for the end user. For a step-by-step walkthrough of creating an application that uses background file transfers, see How to implement background file transfers for Windows Phone 8.

This topic contains the following sections.

The Background Transfer APIs

The background transfer service APIs can be found in the Microsoft.Phone.BackgroundTransfer namespace. The primary programming elements you will use are the BackgroundTransferRequest and the BackgroundTransferService classes. The BackgroundTransferRequest object represents a single transfer request including the target and destination file paths, the transfer method, and the current status of a transfer. The BackgroundTransferService object is used to initiate new transfers and to query for or remove existing file transfers.

Supported Transfer Methods

The Background Transfer Service only supports transfers using HTTP and HTTPS. FTP is unsupported. You can upload and download files in the background with the BackgroundTransferService. The GET HTTP method is supported for downloading files, and the POST method is supported for downloading or uploading files. Set the method for a transfer by using the Method property of the BackgroundTransferRequest object.

File System Restrictions

All background transfers require a local file path. Downloads require a destination path that specifies the location at which the downloaded file will be saved. Uploads require a source path that specifies the location from which the file will be uploaded. All local paths for background transfers must be within the isolated storage for your application within a root directory named “/shared/transfers”. This directory is created by the operating system upon application installation, but if your application deletes or renames this directory, you must re-create it before initiating any file transfers. You can create any additional directory structure you choose underneath the root “/shared/transfers” directory, and you can copy or move files after the transfer is complete to ensure that the background transfer service does not modify the files, but attempting to initiate a transfer using a path outside of the “/shared/transfers” directory will throw an exception.

Reserved Headers

The Headers property of the BackgroundTransferRequest object is used to set the HTTP headers for a transfer request. The following headers are reserved for use by the system and cannot be used by calling applications. Adding one of the following headers to the Headers collection will cause a NotSupportedException to be thrown when the Add(BackgroundTransferRequest) method is used to queue the transfer request:

If-Modified-Since
If-None-Match
If-Range
Range
Unless-Modified-Since

Timeliness of Completion

Background transfers initiated with the Background Transfer APIs will typically begin as soon as the requirements set by the TransferPreferences property as well as system requirements related to battery power and available connections are met. However, because multiple applications may have background transfers queued up, there may be an additional delay before transfers begin while previously added transfers complete.

Windows Phone 8 introduces the Data Sense feature which allows users to request that apps limit data transfers as they approach the limit for their data plan. If the user has turned on the feature, background transfers may be paused depending on the values of following members of the ConnectionCost.

ApproachingDataLimit – If this value is true, background transfers will proceed regardless of whether the app is currently running in the foreground.
OverDataLimit – If this value is true, background transfers will proceed only if the app is currently running in the foreground.
Roaming – If this value is true, background transfers will be paused regardless of whether the app is currently running in the foreground.

For more information on the Data Sense feature and how your app can use it to adjust data usage, see How to adjust data usage using the Data Sense API for Windows Phone 8.

Application Requirements

Important Note:
In addition to the requirements for general applications, there are additional certification requirements for applications that use background file transfers that must be met for an application to be listed in Store. You should consider these requirements as you design and implement your application. For more information, see Additional requirements for specific app types for Windows Phone.

Background Transfer Policies

The operating system enforces a number of restrictions on background transfers related to file size, connection speeds, and device resources. This section lists the policies for background transfers for Windows Phone. Note that the Windows Phone Emulator simulates a device that is connected to Wi-Fi and external power. To verify that an application works under other conditions, you should test on a physical device.

Sizes

Maximum upload file size

Over cellular connection - 5 MB

Over Wi-Fi connection with battery power - 20 MB

Over Wi-Fi connection with external power - 100 MB

Maximum download size over cellular connection

20 MB – If a file exceeds this limit, the TransferPreferences property for the transfer is automatically changed to AllowBattery, which has the effect of requiring Wi-Fi for the transfer.

Maximum download size over Wi-Fi without external power

100 MB – For files larger than 100 MB, you must set the TransferPreferences property of the transfer to None or the transfer will fail. If you do not know the size of a transfer and it is possible that it could exceed this limit, you should set the value to None, meaning that the transfer will only proceed when the phone is connected to external power and has a Wi-Fi connection.

Limits

Maximum outstanding requests in the queue per application (this includes active and pending requests).	25 – Transfers are not removed from the queue automatically when they complete. Applications should use Remove(BackgroundTransferRequest) to remove completed transfers from the queue to keep the slots free for new transfers.
Maximum concurrent transfers across all applications on the device	2
Maximum queued transfers across all applications on the device	500
Maximum number of HTTP headers per request	15
Maximum size of HTTP headers	16 KB each

Policies

The background transfer service will transfer on the following data networks while the app is in the foreground. Transfers will not proceed on these networks while the app is not in the foreground. This limitation is shared by the HttpWebRequest object, so in this respect performing your own transfer does provide any advantages over using background transfers.
- 2G, EDGE, Standard GPRS
On networks that are 3G and higher, background transfers will proceed regardless of whether the app is running in the foreground, assuming all other conditions are met.
The content-length header is required on the server side for files greater than 5 MB. Servers should always return the content-length in responses. Failing to do so can result in severely degraded transfer performance.
Range headers are required on the server side for files greater than 5 MB. Servers should always support range request headers. Failing to do so can result in severely degraded transfer performance.

Slow Transfers

If the network connection of the device drops below the following rates, the transfer will be paused and retried. These limits, expressed in kilobits per second (Kbps), are low and will not typically be hit.

Network medium	Minimum data rate
3G	50 Kbps
Wi-Fi/USB	100 Kbps

Share via