What’s New in Windows Phone 8 (4 out of 8)–Protocol handler and file extensions

November 2, 2012

This post is dedicated to new extensibility feature – ability to associate file extension and protocol type to automatically launch your app when another app launches a specific file type or URI. When launched, a deep link URI is used to send the file (a reference to the file) or URI to application. You can also use the association launching API to launch another app in the same way.

File type association is useful when your app need automatically launch on invoking specific file type from email attachment, NFC tag, text message, another application.

Protocol association is useful when your application need automatically launch on invoking specific URI, such as mailto://, http://, etc.

File associations

Registration to file type (file extension) achieved via FileTypeAssociation element in Extensions element of application manifest. The following code snippet registers application to handle files with “.smpl” and “.sample” extensions:

<FileTypeAssociation Name="SampleLaunch" TaskID="_default" NavUriFragment="fileToken=%s">

  <!--<Logos>

    <Logo Size="Small">small.png</Logo>

    <Logo Size="Medium">medium.png</Logo>

    <Logo Size="Large">large.png</Logo>

  </Logos>-->

  <SupportedFileTypes>

    <FileType>.smpl</FileType>

    <FileType>.sample</FileType>

  </SupportedFileTypes>

</FileTypeAssociation>

Please note optional Logos section (commented in sample) – this section lists an image file to appear beside a file. The files in this section sized/used as follows:

Size Image dimensions Usage
Small 33×33 Email attachments
Medium 69×69 Office hub files list
Large 176×176 IE download list

When the application is launched to handle a particular file type, a deep link URI passed to the application. The URI looks like the following:

/FileTypeAssociation?fileToken={TOKEN_GUID}

Within the URI, the FileTypeAssociation string designates that the source of the URI is a file association and the fileToken parameter contains the file token GUID. Those parameters could be easily parsed and rerouted to internal handler page.

Usually, to handle multiple URI types application defines URI mapper class which parses the inbounding URI and reroutes to application’s page. The sample URI mapper class to handle such URI could look like the following code snippet:

class CustomUriMapper : UriMapperBase

{

    private static string TargetFilePageName = "FilePage.xaml";

    private static string FileTemplate = "/FileTypeAssociation?fileToken=";

    public override Uri MapUri(Uri uri)

    {

        string tempUri = HttpUtility.UrlDecode(uri.ToString());

 

        if (tempUri.Contains("/FileTypeAssociation"))

                return GetFileMappedUri(tempUri);

 

        return uri;

    }

 

    private Uri GetMappedUri(string uri)

    {

        //...

    }

}

Note: this code is partial, application logic is omitted for code brevity.

To URI mapper class used in app by assigning it to RootFrame.UriMapper property in App.xaml.cs after initializing RootFrame object:

//...

RootFrame = new PhoneApplicationFrame();

RootFrame.Navigated += CompleteInitializePhoneApplication;

 

RootFrame.UriMapper = new CustomUriMapper();

 

// Handle navigation failures

RootFrame.NavigationFailed += RootFrame_NavigationFailed;

//..

Once application launched from file association, the URI mapper will intercept the URI and reroute (in sample code above) to FilePage.xaml page. To open the file by received file association, use SharedStorageAccessManager from Windows.Phone.Storage.SharedAccess namespace. SharedStorageAccessManager provides access to files that have been shared with a file association:

//Get token from query string

string fileToken = NavigationContext.QueryString["ID"];

//Resolve filename

var filename = SharedStorageAccessManager.GetSharedFileName(fileToken);

//Copy file to local folder

var file = await SharedStorageAccessManager.CopySharedFileAsync(Windows.Storage.ApplicationData.Current.LocalFolder,

                                                                    fileToken + ".smpl", Windows.Storage.NameCollisionOption.ReplaceExisting,

                                                                    fileToken);

//Open local file

var content = await file.OpenAsync(Windows.Storage.FileAccessMode.Read);

//...

Testing file association is easy with Launcher class from System.Windows namespace. It provides LaunchFileAsync function which starts default app associated with specified file type:

StorageFile recipeFile = await local.GetFileAsync("SampleFile.smpl");

 

if (null != recipeFile)

    await Windows.System.Launcher.LaunchFileAsync(recipeFile);

Note: this functionality is launched from another application which serves as tester app for real application.

 

Protocol associations

A protocol association allows your app to automatically launch when another app launches a special URI. This special URI could look like the following (using in sample for this post):

sample://showSample?ID=1004

To handle protocol, application must manifest new extra in application manifest must (in Extras section):

<Protocol Name="sample" TaskID="_default" NavUriFragment="encodedLaunchUri=%s" />

In this code snippet “sample” is the name of custom protocol which will be used to launch the application.

Once user clicks on hyper link with this protocol, or other application invokes navigation to such protocol the application starts with following deep link URI passed to the application:

/Protocol?encodedLaunchUri=sample://showSample/?ID=1234

Like in file association scenario, it is easy to intercept such links with URI mapper and reroute to internal page in application:

public override Uri MapUri(Uri uri)

{

    string tempUri = HttpUtility.UrlDecode(uri.ToString());

 

    if (tempUri.Contains("/Protocol"))

        return GetMappedUri(tempUri);

 

    return uri;

}

 

private Uri GetMappedUri(string uri)

{

    //...

}

The major difference from file association is that the amount information in URI is much more limited than in file.

To test the application you can create simple HTML file and host on some webhosting (for example this post uses the following HTML file hosted at http://www.alexgolesh.com/sample.html:

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml" >

<head>

    <title>Sample launcher</title>

</head>

<body>

    <h1>Protocol and File extenstion handlers sample</h1>

    <div>

        <h2>This section invokes "sample://" protocol for my blog sample.</h2>

        <a href="sample://showSample?ID=1234">Click here to launch blog sample</a>

    </div>

</body>

</html>

Alternatively, protocol handler can be invoking using same Launcher class from System.Windows namespace as for file association. It provides LaunchUriAsync function which starts default app associated with protocol:

Uri uri = new Uri("sample://showSample?ID=1004");

Windows.System.Launcher.LaunchUriAsync(uri);

Note: this functionality is launched from another application which serves as tester app for real application.

Working sample presented at the following vide

Video of file associations and protocol handler sample

Next time I will blog about hybrid applications which combines native and managed code together.

 

Stay tuned,

Alex

Add comment
facebook linkedin twitter email

Leave a Reply to Flora Cancel Reply

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*

2 comments

  1. KayleeJanuary 17, 2013 ב 7:12

    Keep these articles coming as they’ve oepend many new doors for me.

    Reply
  2. FloraJanuary 19, 2013 ב 4:52

    Appraetnly this is what the esteemed Willis was talkin’ ’bout.

    Reply