Home > Sample chapters > Programming > Windows

Windows Phone 8 Development Internals: Phone and Media Services

In this chapter from Windows Phone 8 Development Internals, learn 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.

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

Type

Task

Description

New in 8

Launchers

BingMapsDirectionsTask

Launches the Maps app, specifying a starting and/or ending location, for which driving or walking directions are displayed (identical to the MapsDirectionsTask).

BingMapsTask

Launches the Maps app centered at the specified or current location (identical to the MapsTask).

ConnectionSettingsTask

Launches a settings dialog with which the user can change the device’s connection settings.

EmailComposeTask

Composes a new email.

MapDownloaderTask

Provides a mechanism for the user to download maps for offline use.

Y

MapUpdaterTask

Provides a mechanism for the user to update map data he has previously downloaded for offline use.

Y

MapsDirectionsTask

Launches the Maps app, specifying a starting and/or ending location, for which driving or walking directions are displayed (identical to BingMapsDirectionsTask).

Y

MapsTask

Launches the Maps app centered at the specified or current location (identical to BingMapsTask).

Y

MarketplaceDetailTask

Launches the Windows Phone Store and displays the details for a specific app.

MarketplaceHubTask

Launches the Windows Phone Store and searches for a particular type of content.

MarketplaceReviewTask

Displays the Windows Phone Store review page for the current app.

MarketplaceSearchTask

Launches the Windows Phone Store and displays the search results from the specified search terms.

MediaPlayerLauncher

Launches Media Player, and plays the specified media file.

PhoneCallTask

Initiates a phone call to a specified number.

SaveAppointmentTask

Provides a mechanism for the user to save an appointment from your app.

Y

SearchTask

Launches Microsoft Bing Search with a specified search term.

ShareLinkTask

Launches a dialog with which the user can share a link on the social networks of her choice. If the user does not have any social networks set up, the Launcher silently fails.

ShareMediaTask

Provides a mechanism for your app to share a media item with one of the media-sharing apps on the phone.

Y

ShareStatusTask

Launches a dialog with which the user can share a status message on the social networks of her choice. If the user does not have any social networks set up, the Launcher silently fails.

SmsComposeTask

Composes a new text message.

WebBrowserTask

Launches Microsoft Internet Explorer and browses to a specific URI.

Choosers

AddWalletItemTask

Launches the Wallet app and allows the user to add the supplied item to his wallet.

Y

AddressChooserTask

Launches the Contacts app with which the user can find an address.

CameraCaptureTask

Opens the Camera app to take a photo.

EmailAddressChooserTask

Provides a mechanism for the user to select an email address from his Contacts List.

GameInviteTask

Shows the game invite screen with which the user can invite players to a multiplayer game session.

PhoneNumberChooserTask

Provides a mechanism for the user to select a phone number from his Contacts List.

PhotoChooserTask

Provides a mechanism for the user to select an image from his Picture Gallery or take a photo.

SaveContactTask

Launches the Contacts app with which the user can save a contact.

SaveEmailAddressTask

Saves an email address to an existing or new contact.

SavePhoneNumberTask

Saves a phone number to an existing or new contact.

SaveRingtoneTask

Launches the Ringtones app with which the user can save a ringtone from your app to the system ringtones list.

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

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

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;
    }
}