Windows Phone 8 : Media and Picture Hubs (part 3) - Integrating into the Pictures Hub, Integrating into the Music and Videos Hub

FIGURE 3 The apps in the Pictures hub

To integrate your application into these parts of the picture experience, you need to include a new section in the WMAppManifest.xml file. This section is called “Extensions”:

<Deployment ...>
  <App ...>
    ...
    <Extensions>
      <!-- Integrate into pictures hub -->
      <Extension ExtensionName="Photos_Extra_Hub"
                 ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5632}"
                 TaskID="_default" />
    </Extensions>
  </App>
</Deployment>

The ExtensionName and ConsumerID are both used to determine the type of integration your application will use (for example, Pictures hub, picture viewer, and picture sharing). The TaskID is used to determine how to launch your application. Using the _default indicates that your application should be launched normally and is typical.

As stated earlier, you can integrate into any or all of the three picture extensions. Each extension has its own entry in the Extensions section of the WMAppManifest.xml file:

<Deployment ...>
  <App ...>
    ...
    <Extensions>

      <!-- Integrate into pictures hub -->
      <Extension ExtensionName="Photos_Extra_Hub"
                 ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5632}"
                 TaskID="_default" />

      <!-- Integrate into picture viewer -->
      <Extension ExtensionName="Photos_Extra_Viewer"
                 ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5632}"
                 TaskID="_default" />

      <!-- Integrate into picture sharing -->
      <Extension ExtensionName="Photos_Extra_Share"
                 ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5632}"
                 TaskID="_default" />

    </Extensions>
  </App>
</Deployment>

A picture extension application will be launched either from one of the picture integration locations (for example, from the Pictures hub) or in the normal way (for example, from the Start menu or app list). You will need to determine which way your application is being launched and show the chosen photo if launched via the Extras menu. This is typically handled by overriding the OnNavigatedTo method of your application’s first page (for instance, MainPage.xaml) and using the NavigationContext property to test for the existence of a token that was passed to your application from the Pictures hub:

public partial class MainPage : PhoneApplicationPage
{
  // ...

  protected override void OnNavigatedTo(NavigationEventArgs e)
  {
    base.OnNavigatedTo(e);

    // If token is in the query string,
    // we launched here from Extras menu
    if (NavigationContext.QueryString.ContainsKey("token"))
    {
      var token = NavigationContext.QueryString["token"];

      // Use Media Library to open the image
      using (MediaLibrary library = new MediaLibrary())
      {
        Picture selectedPicture = library.GetPictureFromToken(token);

        // Use the Picture
        Stream picture = selectedPicture.GetImage();

        // Use the picture. Typically should show it on launch page
      }
    }
  }
  // ...
}

After you see the “token” in the query string, you can use that token to retrieve the picture from the MediaLibrary class by calling the GetPictureFromToken method, as shown earlier.

• Collection: This is the starting point for users to play music/videos/podcasts that are synced onto their phones.

• History: This is a list of recently played items.

• New: This is a list of music and video items newly added to the phone.

• Apps: These are the applications that are integrated into the Music and Videos hub.

• Xbox: This is Xbox-specific integration for SmartGlass and other Xbox apps.

After you specify you are integrating with the phone, you should integrate with the History and New sections of this hub. By using the Media and Videos APIs, your application will automatically be listed in the Marquee section of the hub.

<?xml version="1.0" encoding="utf-8"?>
<Deployment
   xmlns="http://schemas.microsoft.com/windowsphone/2009/deployment"
   AppPlatformVersion="7.0">
  <App xmlns=""
       ProductID="{1f6ccd50-764b-4247-ba61-253a287ab640}"
       Title="FunWithMediaLibrary"
       RuntimeType="Silverlight"
       Version="1.0.0.0"
       Genre="apps.normal"
       Author="FunWithMediaLibrary author"
       Description="Sample description"
       Publisher="FunWithMediaLibrary"
       HubType="1">

Note that there is no way to run and test this behavior with the emulator. You must debug this on a physical device. It is recommended that you use the WPConnect.exe tool to connect the phone to the development computer, as connecting with Zune will not allow you to have access to the Media and Videos hub (showing the “Syncing” message instead).

// You will need an image for the Now Playing section of
// the Hub.
Stream songImage = GetImageForSong();

// Create an object that contains the history information
MediaHistoryItem item = new MediaHistoryItem();
item.Source = ""; // Must Be an empty String
item.ImageStream = songImage;
item.Title = "NowPlaying";
item.PlayerContext.Add("keyString", "mysong.mp3");
MediaHistory.Instance.NowPlaying = item;

When you create the MediaHistoryItem, the Source property must be an empty string. The ImageStream must be a JPEG image that is 358 pixels by 358 pixels in size. It should include your application’s name and logo if any. For the Now Playing section of the Media and Videos hub, the Title must be "NowPlaying". The PlayerContext property is a name/value list of information that you will have access to when an item launches your application.

// Create an object that contains the history information
MediaHistoryItem item = new MediaHistoryItem();
item.Source = "";
item.ImageStream = songImage;
item.Title = "RecentPlay";
item.PlayerContext.Add("keyString", "mysong.mp3");
MediaHistory.Instance.WriteRecentPlay(item);

The differences between this and the Now Playing section are that the Title property must be RecentPlay and you must add it to the MediaHistory via the WriteRecentPlay method. Lastly, images for the History tab are different and must be 173 pixels by 173 pixels instead of the larger Now Playing size. You should not just resize the larger image because the text on that image would likely be unreadable at the smaller size.

// Create an object that contains the new information
MediaHistoryItem item = new MediaHistoryItem();
item.Source = "";
item.ImageStream = songImage;
item.Title = "MediaHistoryNew";
item.PlayerContext.Add("keyString", "mysong.mp3");
MediaHistory.Instance.WriteAcquiredItem(item);

This works identically to adding history items except that the Title must be "MediaHistoryNew" and adding the item to the New section requires that you call the WriteAcquiredItem method. The size of the image is 173 pixels by 173 pixels, just like the History section example.

protected override void OnNavigatedTo(NavigationEventArgs e)
{
  base.OnNavigatedTo(e);

  // If "keyString" is in the query string, we were launched
  // from the hub
  if (NavigationContext.QueryString.ContainsKey("keyString"))
  {
    var key = NavigationContext.QueryString["keyString"];

    // Find the media by your special key
    Song song = FindSongByKey(key);

    // Play the song normally

  }
}

By retrieving the key from the NavigationContext’s QueryString, you can retrieve the keyString you added with the MediaHistoryItem. After you have it, you can use the contents of the keyString to find the appropriate piece of media to play.