Windows Phone 8 Development Internals: Phone and Media Services

For app developers, a key feature of a smartphone—beyond the ability to make and receive cellular calls, of course—is the degree to which you can integrate your app with the built-in phone and media services. Windows Phone provides a set of Launchers and Choosers, which is the way that the app platform repurposes built-in apps, such as the browser, search, calendar, email, and so on. You can take advantage of these features within your own apps.

The platform also provides extensive support for media services, including audio and video playback. You can choose from several different sets of media-related application programming interfaces (APIs), depending on the specific requirements of your app. If you have a simple requirement for media playback, you can use the MediaPlayerLauncher. If you need more flexibility, the MediaElement type might suit your needs better. If you need more fine-grained control over the media file content, you can use the MediaStreamSource API, and so on. In this chapter, we examine the various levels of app support and your choices for integrating with—and extending—standard system features, including built-in phone apps, audio and video services, and search. This is an area where relatively little has changed between Windows Phone 7 and Windows Phone 8, so most of the programming techniques described in this chapter work on both versions of the platform.

Launchers and Choosers

Both Launchers and Choosers are API mechanisms for invoking existing apps and services on the phone. In the API, they’re all called “tasks.” The difference between Launchers and Choosers is that Launchers start a feature but don’t return a value, whereas Choosers launch a feature and do return a value. Table 5-1 summarizes these tasks. The phone has a range of very useful built-in apps, exposed for programmatic integration via a very simple set of APIs.

Invoking a Launcher or Chooser causes your app (the invoking app) to be deactivated. Some Choosers run in your app session, so if you press and hold the back key, you don’t see your app as a separate instance that you can activate; rather, you see the Chooser screenshot listed for your app. As you would expect, the inter-app navigation behavior is consistent with all other inter-app navigations. Users can return to the original app upon completing the task inside the Launcher/Chooser, or they can use the Back key. If the Launcher/Chooser has multiple pages, the Back key will navigate the user through the previous pages and, finally, back to the calling app. In the same manner, if the user navigates forward through multiple apps, this can result in the original calling app falling off the backstack, as normal. Also, the Chooser is auto-dismissed if the user forward navigates away from it. Table 5-1 lists the full set of available Launchers and Choosers.

Table 5-1. Launchers and Choosers

Of the new tasks introduced in Windows Phone 8, maps are discussed in Chapter 18 appointments are discussed in Chapter 15 and wallet is discussed in Chapter 20. However, the general pattern for invoking Launchers and Choosers is consistent across all tasks. The LaunchersAndChoosers solution in the sample code demonstrates this pattern. Buttons are available to invoke a PhoneCallTask, WebBrowserTask, SearchTask, and EmailAddressChooserTask, as shown in Figure 5-1.

In general, the app code for invoking Launchers and Choosers is very simple. The app platform provides easy-to-use wrappers for all of the app-accessible system tasks on the device. The basic steps for using a Launcher are as follows:

1. Create an instance of the type that represents the specific Launcher feature that you want to use.

2. Set properties on the object as appropriate.

3. Invoke the Show method.

Figure 5-1 Many standard tasks are exposed programmatically as Launchers and Choosers.

In this example, when the user taps the Phone button, the app instantiates a PhoneCallTask object and calls Show, which prompts the user to confirm the outgoing call. This feature is protected by the ID_CAP_PHONEDIALER capability, so you need to update your app manifest to include this; otherwise, the attempt to invoke PhoneCallTask.Show will throw a security exception.

PhoneCallTask phone = new PhoneCallTask();
phone.PhoneNumber = phoneNumber.Text;
phone.Show();

The Search button invokes SearchTask.Show; it is equally simple to use, following the exact same pattern.

SearchTask search = new SearchTask();
search.SearchQuery = searchText.Text;
search.Show();

The first time the user selects the search feature, he gets a prompt from the system, as shown in Figure 5-2 (left). This is because the search feature can make use of the user’s location, and the user must be given the option to allow access to this information. If and when the user proceeds with the search, the task displays a scrolling list that contains the Bing search results for the specified term, as illustrated in Figure 5-2 (right).

Figure 5-2 Invoking a search task for the first time triggers a permission request to the user.

Using the WebBrowserTask follows the same pattern. Windows Phone 7 developers might be accustomed to using the URL string property of this task, but this is now obsolete, and you should instead use the Uri property (of type Uri, and named Uri).

WebBrowserTask browser = new WebBrowserTask();
browser.Uri = new Uri("http://" +browseText.Text);
browser.Show();

Using the EmailAddressChooserTask is only marginally more involved. So far, we’ve shown how to use Launchers, but the EmailAddressChooserTask is a Chooser, which means it returns a value to the calling app. The basic steps for using a Chooser are as follows:

1. Create an instance of the type that represents the specific Chooser feature that you want to use. It is common to declare this as a field in your page class.

2. Hook up the Completed event on the object (or provide an inline delegate or lambda), which will be invoked when the Chooser task completes.

3. Set properties on the object as appropriate.

4. Invoke the Show method.

5. In your Completed event handler or delegate, process the return value from the Chooser.

The code snippet that follows illustrates this pattern. In this example, the email address that the user has selected from the contacts list offered by the Chooser is then pasted into the corresponding TextBox back in the sample app. It is important to note that you must declare the Chooser object as a class field in the page where it is used. You must also call the Chooser constructor to set up the field—and also hook up the Completed event—within the page constructor. The reason for this is to ensure that your app will be called back correctly after it has been deactivated and then reactivated for situations in which it was tombstoned and then rehydrated on return from the Chooser.

private EmailAddressChooserTask emailAddress = new EmailAddressChooserTask();
public MainPage()
{
    InitializeComponent();
    emailAddress.Completed += emailAddress_Completed;
}
private void emailButton_Click(object sender, RoutedEventArgs e)
{
    emailAddress.Show();
}
private void emailAddress_Completed(object sender, EmailResult e)
{
    if (e.TaskResult == TaskResult.OK)
    {
        emailText.Text = e.Email;
    }
}