How to respond to requests for directions for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic describes how to write an app that responds to requests for driving or walking directions when called by another app installed on the phone. The other app request directions by using the ms-drive-to or ms-walk-to Uri scheme.

Important Note:

How to provide turn-by-turn directions is beyond the scope of this topic and is not described here. The code sample in this topic simply displays the destination specified in the request.

For a sample that demonstrates some of the tasks described in this topic, download the Navigation URI scheme sample.

For more info about using a Uri to launch another app, see Auto-launching apps using file and URI associations for Windows Phone 8. For info about how to write an app that requests directions, see How to request driving or walking directions for Windows Phone 8.

Consider the possibility of adding text-to-speech output. For more info, see Text-to-speech (TTS) for Windows Phone 8.

This topic contains the following sections.

Registering to handle a Uri association

To register to handle a Uri association

  • In the Extensions element of the app manifest file, which must immediately follow the Tokens element, use the following format to specify the navigation protocol or protocols that your app can handle. Your app does not have to handle both Uri associations. For more info about editing the app manifest file, see How to modify the app manifest file for Windows Phone 8.

        <Extensions>
          <Protocol Name="ms-drive-to" NavUriFragment="encodedLaunchUri=%s" TaskID="_default"/>
          <Protocol Name="ms-walk-to" NavUriFragment="encodedLaunchUri=%s" TaskID="_default"/>
        </Extensions>
    

Listening for a Uri

To listen for a Uri

  1. Create a Uri mapping class to map the request received from the calling app to a page in your app. Here is an example of a Uri mapping class that parses the Uri and calls the ShowDestination.xaml page with the arguments required by the page.

        class DirectionsRequestUriMapper : UriMapperBase
        {
    
            public override Uri MapUri(Uri uri)
            {
                string tempUri = Uri.UnescapeDataString(uri.ToString());
    
                // Does the Uri contain a request for driving directions or walking directions?
                if (tempUri.Contains("ms-drive-to") || tempUri.Contains("ms-walk-to"))
                {
                    // Parse the Uri.
                    char[] uriDelimiters = { '?', '=', '&' };
                    string[] uriParameters = tempUri.Split(uriDelimiters);
                    string destLatitude = uriParameters[4];
                    string destLongitude = uriParameters[6];
                    string destName = uriParameters[8];
    
                    // Map the request for directions to the ShowDestination page of the app.
                    return new Uri(
                        "/ShowDestination.xaml?" +
                        "latitude=" + destLatitude + "&" +
                        "longitude=" + destLongitude + "&" +
                        "name=" + destName,
                        UriKind.Relative);
                }
                // Otherwise, handle the Uri normally.
                return uri;
            }
        }
    

    First, the sample code decodes the Uri received from the calling app.

    Here is an example of the encoded Uri that your app receives from the sample shown earlier in this topic:

    /Protocol?encodedLaunchUri=ms-drive-to%3A%3Fdestination.latitude%3D47.6451413797194%26destination.longitude%3D-122.141964733601%26destination.name%3DRedmond%2C%20WA

    Next the sample splits the Uri into its component parts:

    1. (array index 0) /Protocol

    2. (array index 1) uri

    3. (array index 2) ms-drive-to

    4. (array index 3) destination.latitude

    5. (array index 4) 47.6451413797194

    6. (array index 5) destination.longitude

    7. (array index 6) -122.141964733601

    8. (array index 7) destination.name

    9. (array index 8) Redmond, WA

    Finally the sample assembles the following Uri to call the ShowDestination.xaml page with the arguments required by the page:

    /ShowDestination.xaml?latitude=47.6451413797194&longitude=-122.141964733601&name=Redmond, WA

  2. From Solution Explorer, open the App.xaml.cs code file. Add the following line of code to the InitializePhoneApplication method to enable the Uri mapping class.

            private void InitializePhoneApplication()
            {
                ...
    
                RootFrame = new PhoneApplicationFrame();
                ...
    
                // Assign the Uri mapper class to the application frame.
                RootFrame.UriMapper = new DirectionsRequestUriMapper();
    
                ...
    
            }
    

Handling the Uri

To handle the Uri

  1. Create the target page that handles the request for directions to the specified destination. This sample creates a page named ShowDestination.xaml that simply displays the parameter values passed to the page in the Uri.

    The starting point is not specified in the request, and is assumed to be the current location. Before you use location services to get the current location, make sure that the user has given consent to use the phone’s location. For more info and sample code, see How to get the phone's current location for Windows Phone 8.

  2. In ShowDestination.xaml, add a textbox to the page to display the parameter values.

            <!--ContentPanel - place additional content here-->
            <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
                <TextBox x:Name="tbDestinationParams" HorizontalAlignment="Left" Height="516" Margin="10,10,0,0" TextWrapping="Wrap" VerticalAlignment="Top" Width="436" IsReadOnly="True"/>
            </Grid>
    
  3. In ShowDestination.xaml.cs, add code to process the Uri in the page’s OnNavigatedTo event. This code simply displays the parameter values passed to the page in the Uri.

            protected override void OnNavigatedTo(NavigationEventArgs e)
            {
                base.OnNavigatedTo(e);
    
                    // Extract the arguments from the query string passed to the page.
                    IDictionary<string, string> uriParameters = this.NavigationContext.QueryString;
                    string destLatitude = uriParameters["latitude"];
                    string destLongitude = uriParameters["longitude"];
                    string destName = uriParameters["name"];
    
                    this.tbDestinationParams.Text = "\tlatitude = " + destLatitude + "\r\n" +
                                                    "\tlongitude = " + destLongitude + "\r\n" +
                                                    "\tname = " + destName;
    
            }
    

The following screen shot shows the parameter values displayed by the preceding sample.