Receiving a File Launch Request
,By associating your app with a file extension, the Windows Phone OS sends requests to open any files of the registered type to your app. It does so by launching your app and providing a deep link URI that contains a file token—a guid that is used to retrieve a file from storage.
It is your app’s responsibility to recognize the incoming file launch URI and redirect to a page that can handle the request.
Detecting a File Launch
When an app is the subject of a file association, it is launched and navigated to a URI beginning with this text: /FileTypeAssociation.
The value of a fileToken query string parameter is used to retrieve the file from storage. The following example shows a deep-link URI from a file launch:
/FileTypeAssociation?fileToken=54195f9-1de0-65d1-3f21-c533f1909a18
When your app is launched as a result of a file association, the app can use a URI mapping to redirect to a page designed to handle the launch request.
The App.xaml file in the WPUnleashed.FileAndProtocolAssociations project has a UriMapping for the /FileTypeAssociation URI that redirects to the FileView.xaml page, which is shown in the following excerpt:
<Application.RootVisual>
<phone:PhoneApplicationFrame
Navigated="CompleteInitializePhoneApplication"
NavigationFailed="RootFrame_NavigationFailed">
<phone:PhoneApplicationFrame.UriMapper>
<navigation:UriMapper>
<navigation:UriMapper.UriMappings>
<navigation:UriMapping Uri="/FileTypeAssociation"
MappedUri="/FileView.xaml" />
...
</navigation:UriMapper.UriMappings>
</navigation:UriMapper>
</phone:PhoneApplicationFrame.UriMapper>
</phone:PhoneApplicationFrame>
</Application.RootVisual>
The fileToken query string parameter that is present in the incoming /FileTypeAssociation URI is automatically included during the mapping process.
Tip
An alternative to defining the URI mapping in the App.xaml file is to create a custom URI mapper as described in Chapter 31, “Extending the Search Experience.” Creating a custom URI mapper allows you to programmatically determine the destination URI using factors other than the content of the deep-link URI.
The NavigationContext’s QueryString property is an IDictionary<string, string>. It contains the fileToken parameter. The landing page’s OnNavigatedTo method passes the dictionary to the viewmodel’s Load method, as shown:
protected override void OnNavigatedTo(NavigationEventArgs e)
{
base.OnNavigatedTo(e);
ViewModel.Load(NavigationContext.QueryString);
}
Retrieving a Launched File
In the sample for this section, processing of the query string is performed by the FileViewModel in the WPUnleashed.FileAndProtocolAssociations project (see Listing 30.2).
The fileToken parameter that is passed to your app within the deep-link URI allows you to retrieve the file using the Windows Phone SDK’s storage API.
The SharedStorageAccessManager retrieves the name of the file using the token and then copies the file to the app’s private storage area where it can be freely accessed by the app.
The SharedStorageAccessManager is part of the WinPRT API. The class has two static methods, GetSharedFileName and CopySharedFileAsync, that are designed specifically for the scenario presented in this section.
Note
The new Windows.Storage API allows your app to store and retrieve files in your app’s private storage area and is the WinPRT equivalent of the Silverlight Isolated Storage API that you may already be familiar with. See Chapter 28, “Preserving App State and Settings.”
LISTING 30.2. FileViewModel.Load Method
public async Task Load(IDictionary<string, string> queryStringDictionary)
{
string fileToken;
if (!queryStringDictionary.TryGetValue("fileToken", out fileToken))
{
MessageService.ShowError(
"Unable to locate the file token in the query string.");
return;
}
string fileName = SharedStorageAccessManager.GetSharedFileName(fileToken);
StorageFolder folder = ApplicationData.Current.LocalFolder;
string tempFileName = "temp_" + fileName;
IStorageFile file = await SharedStorageAccessManager.CopySharedFileAsync(
folder, tempFileName, NameCollisionOption.ReplaceExisting, fileToken);
ReadFile(file);
}
The viewmodel’s ReadFile method uses more of the new WinRT API to retrieve the content of the file using the asynchronous IStorageFile OpenAsync method (see Listing 30.3). The string that is read from the file is set as the viewmodel’s FileContent property.
LISTING 30.3. FileViewModel.ReadFile Method
async void ReadFile(IStorageFile file)
{
string fileContent;
using (IRandomAccessStream streamOpenedFile
= await file.OpenAsync(FileAccessMode.Read))
{
using (IInputStream inputStream = streamOpenedFile.GetInputStreamAt(0))
{
using (StreamReader reader
= new StreamReader(inputStream.AsStreamForRead()))
{
fileContent = await reader.ReadToEndAsync();
}
}
}
FileContent = fileContent;
}
The FileView.xaml page has a binding to the viewmodel’s FileContent property, as shown:
<TextBlock Text="{Binding FileContent, StringFormat='"{0}"'}"
TextWrapping="Wrap"
Style="{StaticResource PhoneTextExtraLargeStyle}"/>
In the next section you look at launching a file from another app that is then displayed on the FileView page.