How to receive files (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]
Sharing files requires a little more preparation than simpler data types, such as text. When sharing files, you need to consider how long it might take to process the files.
If you think your app needs time to process the files that a user wants to share, be sure to call reportStarted before you begin processing them. This method ensures that the system keeps your app alive until it's finished processing. After your app completes its processing, call reportCompleted to finish the sharing operation. To learn more, see "Report extended share status" in the Quickstart: Receiving shared content.
What you need to know
Technologies
Prerequisites
- You should be familiar with Visual Studio and its associated templates.
- You should be familiar with JavaScript.
Instructions
Step 1: Support the Share contract.
Before your app can receive shared content, you have to declare that it supports the Share contract. This contract lets the system know that your app is available to receive content. If you're using a Microsoft Visual Studio template to create your app, here's how you support the share target contract:
- Open the manifest file (package.appxmanifest).
- Open the Declarations tab.
- Choose Share Target from the Available Declarations list.
- Click Add to add support for the Share Target contract in your app.
Step 2: Specify file types that your app supports.
You can specify the file types that your app supports by specifying their extensions in the app manifest:
- Open the manifest file.
- In the Data Formats section, click Add New.
- Type the file name extension, such as ".txt" (without the quotes).
- Repeat the previous step for any additional file types.
The preceding steps add the following section to the manifest:
<Extensions>
<Extension Category="windows.shareTarget">
<ShareTarget>
<SupportedFileTypes>
<FileType>.txt</FileType>
</ShareTarget>
</Extension>
</Extensions>
Note You don’t need to specify StorageItems in the Data formats section. Support for this is inferred from the SupportedFileTypes section in the manifest. If your app supports any file types, you can specify them in the manifest by checking Supports any file type.
Note You can specify a different entry point when your app is activated for the Share Target contract. To do this, modify the Start page entry in App settings section of the Share Target declaration in the package manifest. We highly recommend that you also use a separate JavaScript file that handles activation for this page. For an example, check out the Sharing content target app sample.
Step 3: Add an event handler to detect when your app is activated.
When a user selects your app to share content, the system activates your app. Because there are many ways this can happen, you need to add code that detects why the activation occurred. You do this by checking the value of the kind property.
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
// The application has been launched. Initialize as appropriate.
} else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
...
}
};
Step 4: Get the ShareOperation object.
The ShareOperation object contains all the data that your app needs to get the content that a user wants to share.
shareOperation = args.detail.shareOperation;
Step 5: Return from the activated event handler quickly.
The activated event handler must return quickly. Queue an asynchronous event from activated event handler so that share data processing takes placed after the activated event returns.
WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });
The remaining steps implement the shareReady function.
Step 6: Check to see if the DataPackageView contains StorageItems.
The ShareOperation object contains a DataPackageView object. This object is a read-only version of the DataPackage object that the source app used to create the data. Use this object to see if the content being shared contains StorageItems.
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
// Data being shared contains one or more StorageItem. Code to process the StorageItems goes here.
}
Checking whether the DataPackage contains the data format you are interested in is good practice, even if your app supports only one format. This makes it easier to support other data formats later.
Step 7: Process the files.
To get the files, call the DataPackageView.GetStorageItemsAsync method.
shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
var fileList = "";
for (var i = 0; i < storageItems.size; i++) {
fileList += storageItems.getAt(i).name;
if (i < storageItems.size - 1) {
fileList += ", ";
}
}
// In this example, we only display the file names. To do this, you need
// a <div> element with an id of "output" in your HTML page.
// In your app, replace this with whatever is appropriate for your scenario.
document.getElementById("output").innerText = "Files: " + fileList;
});
Note
Processing files can take time. It is important that you don't force the user to wait until your app is finished loading and processing data. On Windows 8.1, you can call the reportStarted method to let the system know that your app has started to process the content being shared. The system keeps your app alive until you call reportCompleted—even if the user dismisses your app to return to the source app. For more information, see "Report extended share status" in the Quickstart: Receiving shared content.
Step 8: Call reportCompleted.
After your app successfully finishes sharing the content, call reportCompleted. After you call this method, the system dismisses your app.
shareOperation.reportCompleted();
Remarks
Check out our Sharing content target app sample code sample to see the entire end-to-end experience of an app receiving text as part of sharing.
Complete example
var shareOperation = null;
function shareReady(args) {
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
var fileList = "";
for (var i = 0; i < storageItems.size; i++) {
fileList += storageItems.getAt(i).name;
if (i < storageItems.size - 1) {
fileList += ", ";
}
}
// In this example, we only display the file names. To do this, you need
// a <div> element with an id of "output" in your HTML page.
// In your app, replace this with whatever is appropriate for your scenario.
document.getElementById("output").innerText = "Files: " + fileList;
});
}
}
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
// The app has been launched.
args.setPromise(WinJS.UI.processAll());
} else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
// This app was activated for the Share contract.
args.setPromise(WinJS.UI.processAll());
// We receive the ShareOperation object as part of the eventArgs.
shareOperation = args.detail.shareOperation;
// We queue an asychronous event so that working with the ShareOperation
// object does not block or delay the return of the activation handler.
WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });
}
};
Related topics
Sharing content target app sample
Quickstart: Receiving shared content
Windows.ApplicationModel.DataTransfer