How to make asynchronous calls in your datarequested handler (HTML)
[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]
Here, we'll show you how to produce data asynchronously in response to a datarequested event. If your app performs any asynchronous operations in response to a datarequested event, it needs to acquire a DataRequestDeferral object first. Acquiring a deferral object lets the system know that your call to add data to the DataPackage might happen after the delegate returns.
Note If you're just sharing text or a link, you don't need the code in this topic. It's faster to use the setText and setUri methods.
What you need to know
Technologies
Prerequisites
- You should be familiar with Microsoft Visual Studio and its associated templates.
- You should be familiar with JavaScript.
- You should understand how to get files and other data, such as by using FileOpenPicker.
Instructions
Step 1: Set up your app as share source
The DataTransferManager object is the main starting point for any share operation. You’ll add a datarequested event handler on the DataTransferManager object in the activated event handler of your app. The datarequested event occurs when the user invokes the Share charm.
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareAsyncHandler);
The remaining steps implement the shareAsyncHandler function.
Step 2: Get a DataRequest object
When a datarequested event occurs, your app receives a DataRequest object. This object contains a DataPackage that you can use to provide the content that the user wants to share.
var request = e.request;
Step 3: Set title and description properties
request.data.properties.title = "Async Share Example";
request.data.properties.description =
"Demonstrates how to make asynchronous calls from a datarequested event handler.";
Step 4: Get a deferral object
To get a deferral object, call getDeferral.
var deferral = request.getDeferral();
Step 5: Make asynchronous call to prepare data
You can use any of the methods that the DataPackage supports to add content. Here, we use setStorageItems to share a file.
Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\logo.png").done(function (storageFile) {
request.data.setStorageItems([storageFile]);
});
Step 6: Call the complete method
The DataRequestDeferral.complete method lets the system know that the data is ready for sharing.
deferral.complete();
You must also call DataRequestDeferral.complete in the error handler of the asynchronous call.
Complete example
function shareAsyncHandler(e) {
var request = e.request;
request.data.properties.title = "Async Share Example";
request.data.properties.description =
"Demonstrates how to make asynchronous calls from a datarequested event handler.";
var deferral = request.getDeferral();
Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\logo.png").done(function (storageFile) {
request.data.setStorageItems([storageFile]);
deferral.complete();
}, function (err) {
deferral.complete();
});
}
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
// This app was recently launched; register it as share source.
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareAsyncHandler);
} else {
// TODO: This app was reactivated from suspension.
// Restore the app state here.
}
args.setPromise(WinJS.UI.processAll());
}
};
Related topics
Sharing content source app sample
How to support pull operations