Language: HTML | XAML

How to make asynchronous calls in your datarequested handler (HTML)

Applies to Windows only

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
Sharing and exchanging data
How to support pull operations
Quickstart: Sharing content
DataPackage
Windows.ApplicationModel.DataTransfer
Windows.ApplicationModel.DataTransfer.Share

 

 

Show:
© 2014 Microsoft