Background transfer API in universal Windows apps: what you need to know

This blog was written by Himadri Sarkar, Program Manager, Windows Networking

With the Visual Studio 2013 Update 2, we can now build Windows Store and Windows Phone Store apps from a single source project. Because the WinRT Windows.Networking.BackgroundTransfer API is available both for Windows Store and Windows Phone apps, it is the API to use for background transfers in any universal app project. However, there are a few usage and behavioral differences between the two platforms that you should be aware of.

API differences

Though the whole Windows.Networking.BackgroundTransfer API namespace is available to Windows and Windows Phone, there are some differences as described in this section.

Unconstrained Downloads and Unconstrained Uploads are not available on Windows Phone

Due to the resource-constrained nature of Windows Phone and also differences in the resource management policies between Windows Phone and Windows, the APIs for unconstrained mode downloads and uploads (RequestUnconstrainedDownloadsAsync and RequestUnconstrainedUploadsAsync) are not supported on Phone. Calls to these APIs will compile successfully but will throw a “Not Implemented” exception at run time. The best way to handle them in a universal app project is to keep them inside the #ifdef directive for the Windows app (for C#, VB, and C++; C# shown here):

For apps written in HTML, CSS, and JavaScript where you don’t have compiler directives, you’ll need to instead place this code in a function that’s defined separately in each platform-targeted project, and then call that function from the shared code.

ContentPrefetcher class is not available on Windows Phone

The ContentPrefetcher class (in Windows.Networking.BackgroundTransfer) allows apps to suggest which web resources the system might pre-fetch to improve networking performance. However, this class is available only in Windows, so its use should again be wrapped with #ifdef directives for a Windows app in a universal app project.

Additional state in the BackgroundTransferStatus enumeration for Windows Phone

BackgroundTransfer operations or tasks can get paused due to resource limitations on both Windows and Windows Phone platforms. However, on Windows Phone the chances of transfers getting paused are much higher and hence Windows Phone has an additional BackgroundTransferStatus enumeration value called PausedSystemPolicy. Windows Phone will pause a transfer and put it into the PausedSystemPolicy state under the following conditions:

• Battery Saver gets activated on the phone
  
• When the phone’s cellular network condition is 2G and the app is not in the foreground
  
• The battery power condition of the phone prevents the transfer to continue
  
• The background task did not get enough memory or CPU resources to run
  

If you have a switch/case statement in your universal app handling the BackgroundTransferStatus enumeration, be sure to again wrap your use of PausedSystemPolicy with an #ifdef directive for a Windows Phone app (C#, VB, and C++; C# shown here):

For apps written in HTML, CSS, and JavaScript, you’ll again need to isolate the code within each platform-targeted project.

Behavioral Differences

Even though the WinRT BackgroundTransfer APIs are converged, there are subtle differences in behavior between the Windows and Windows Phone platforms. These do not affect the programming pattern, but knowing them helps when testing a universal app.

Transfers don’t pause when the app is terminated in Windows Phone

In Windows Phone, the chances of an app getting terminated when it is in the suspended state is much higher than in Windows due to lower CPU and memory resources available. To increase the reliability of the background transfers, even if the app gets terminated, the corresponding background transfer process will keep running to complete the transfers in the background unless the system needs more memory to be reclaimed for a higher priority task. On Windows, this process is terminated along with the app.

Network Data Cost Policy is different in Windows Phone

The background transfer APIs already have the concept of network cost built in, and developers can use the BackgroundTransferCostPolicy enumeration to indicate the cost behavior for their transfers in the app. However, the behavior with regards to the device’s network cost state is slightly different between Windows and Windows Phone. The following table explains when the transfer is allowed under different data state conditions. (The conditions marked in bold are specific to Windows Phone.)

Network State on the Device

UnrestrictedOnly

Default

Always

Unmetered connection (e.g., WiFi)

Allow

Allow

Allow

Metered connection (e.g., 3G), not roaming

Deny

Allow

Allow

Metered connection, not roaming, and

… the user checked “Restrict background data” in Data Sense and

… the user is under their data limit, and

… the user is on track to exceed their data limit

Deny

Deny

Allow

Metered connection, and

… the user checked “Restrict background data” in Data Sense, and

… the user is over their data limit

Deny

Deny

Deny

Metered connection, roaming

Deny

Deny

Allow

Metered connection, roaming, and

… the user checked “Restrict background data when roaming” in Data Sense

Deny

Deny

Deny

Metered connection, and

… the network does not support simultaneous voice and data (e.g., 2G), and

… the app that started the transfer is not in the foreground

Deny

Deny

Deny

Resource Management is different in Windows Phone

There are differences in the way resource management is done for the background tasks in Windows Phone and Windows. The same also applies to background transfers. In Windows Phone there is a time-based battery quota which is applied to background transfers to ensure that the phone battery health is preserved. Windows, on the other hand, has a network quota-based resource management policy.

Conclusion

Overall, because the WinRT BackgroundTransfer APIs are converged between the Windows and Windows Phone platforms, it is easily used within a universal app project. Only minor differences exist between the two, which are easily handled in your code and in your testing process.

For more details on using the API, refer to the Background Transfer sample and Background Transfer API Documentation.

Continue reading...