Quickstart: Accessing HomeGroup content (XAML)

Articolo
10/13/2015

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

Access content stored in the user's HomeGroup folder, including pictures, music, and videos.

Prerequisites

Understand async programming for Windows Runtime apps using C++, C#, or Visual Basic

You can learn how to write asynchronous apps in Quickstart: Calling asynchronous APIs in C# or Visual Basic.
App capabilty declarations

To access HomeGroup content, the user's machine must have a HomeGroup set up and your app must have at least one of the following capabilities: Pictures library, Music library, or Videos library. When your app gets the HomeGroup folder, it will see only the libraries that correspond to the capabilities declared in your app's manifest. Learn more about these capabilities in App capability declarations.

Note Content in the Documents library of a HomeGroup isn't visible to your app regardless of the capabilities declared in your app's manifest and regardless of the user's sharing settings.
Understand how to use file pickers

You typically use the file picker to access files and folders in the HomeGroup. To learn how to use the file picker, see Quickstart: Accessing files with file pickers file pickers.
Understand file and folder queries

You can use queries to enumerate files and folders in the HomeGroup. To learn about file and folder queries, see Quickstart: Accessing files programmatically.

Open the file picker at the HomeGroup

Follow these steps to open an instance of the file picker that lets the user pick files and folders from the HomeGroup:

Create and customize the file picker

Use FileOpenPicker to create the file picker, and then set the picker's SuggestedStartLocation to PickerLocationId.HomeGroup. Or, set other properties that are relevant to your users and your app. For guidelines to help you decide how to customize the file picker, see Guidelines and checklist for file pickers

This example creates a file picker that opens at the HomeGroup, includes files of any type, and displays the files as thumbnail images:
```
Windows.Storage.Pickers.FileOpenPicker picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.HomeGroup;
picker.FileTypeFilter.Clear();
picker.FileTypeFilter.Add("*");
```
Show the file picker and process the picked file.

After you create and customize the file picker, let the user pick one file by calling FileOpenPicker.PickSingleFileAsync, or multiple files by calling FileOpenPicker.PickMultipleFilesAsync.

This example displays the file picker to let the user pick one file:
```
Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();

if (file != null)
{
    // TODO: Do something with the file.
}
else
{
    // TODO: No file returned. Handle the error.
}
```

Search the HomeGroup for files

This section shows how to find HomeGroup items that match a query term provided by the user.

Get the query term from the user.

Here we get a query term that the user has entered into a TextBox control called SearchQuery:
```
string queryTerm = SearchQuery.Text;
```

Set the query options and search filter.

Query options determine how the search results are sorted, while the search filter determines which items are included in the search results.

This example sets query options that sort the search results by relevance and then the date modified. The search filter is the query term that the user entered in the previous step:

Windows.Storage.Search.QueryOptions queryOptions = 
        new Windows.Storage.Search.QueryOptions(Windows.Storage.Search.CommonFileQuery.OrderBySearchRank, null);
queryOptions.UserSearchFilter = queryTerm.Text;
Windows.Storage.Search.StorageFileQueryResult queryResults = 
        Windows.Storage.KnownFolders.HomeGroup.CreateFileQueryWithOptions(queryOptions);

Run the query and process the results.

The following example runs the search query in the HomeGroup and saves the names of any matching files as a list of strings.

System.Collections.Generic.IReadOnlyList<Windows.Storage.StorageFile> files = 
        await queryResults.GetFilesAsync();
if (files.Count > 0)
{
    outputString += (files.Count == 1) ? "One file found\n" : files.Count.ToString() + " files found\n";
    foreach (Windows.Storage.StorageFile file in files)
    {
        outputString += file.Name + "\n";
    }
}

Search the HomeGroup for a particular user's shared files

This section shows you how to find HomeGroup files that are shared by a particular user.

Get a collection of HomeGroup users.

Each of the first-level folders in the HomeGroup represents an individual HomeGroup user. So, to get the collection of HomeGroup users, call GetFoldersAsync retrieve the top-level HomeGroup folders.
```
System.Collections.Generic.IReadOnlyList<Windows.Storage.StorageFolder> hgFolders = 
    await Windows.Storage.KnownFolders.HomeGroup.GetFoldersAsync();
```

Find the target user's folder, and then create a file query scoped to that user's folder.

The following example iterates through the retrieved folders to find the target user's folder. Then, it sets query options to find all files in the folder, sorted first by relevance and then by the date modified. The example builds a string that reports the number of files found, along with the names of the files.

bool userFound = false;
foreach (Windows.Storage.StorageFolder folder in hgFolders)
{
    if (folder.DisplayName == targetUserName)
    {
        // Found the target user's folder, now find all files in the folder.
        userFound = true;
        Windows.Storage.Search.QueryOptions queryOptions = 
            new Windows.Storage.Search.QueryOptions(Windows.Storage.Search.CommonFileQuery.OrderBySearchRank, null);
        queryOptions.UserSearchFilter = "*";
        Windows.Storage.Search.StorageFileQueryResult queryResults = folder.CreateFileQueryWithOptions(queryOptions);
        System.Collections.Generic.IReadOnlyList<Windows.Storage.StorageFile> files = await queryResults.GetFilesAsync();

        if (files.Count > 0)
        {
            string outputString = "Searched for files belonging to " + targetUserName + "'\n";
            outputString += (files.Count == 1) ? "One file found\n" : files.Count.ToString() + " files found\n";
            foreach (Windows.Storage.StorageFile file in files)
            {
                outputString += file.Name + "\n";
            }
    }
}

Stream video from the HomeGroup

Follow these steps to stream video content from the HomeGroup:

Include a MediaElement in your app.

A MediaElement lets you play back audio and video content in your app. For more information on audio and video playback, see Quickstart: Creating a media player app and Quickstart: Video and audio.
```
<Grid x:Name="Output" HorizontalAlignment="Left" VerticalAlignment="Top" Grid.Row="1">
    <MediaElement x:Name="VideoBox" HorizontalAlignment="Left" VerticalAlignment="Top" Margin="0" Width="400" Height="300"/>
</Grid>
```

Open a file picker at the HomeGroup and apply a filter that includes video files in the formats that your app supports.

This example includes .mp4 and .wmv files in the file open picker.

Windows.Storage.Pickers.FileOpenPicker picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.HomeGroup;
picker.FileTypeFilter.Clear();
picker.FileTypeFilter.Add(".mp4");
picker.FileTypeFilter.Add(".wmv");
Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();

Open the the user's file selection for read access, and set the file stream as the source for the MediaElement, and then play the file.

if (file != null)
{
    var stream = await file.OpenAsync(Windows.Storage.FileAccessMode.Read);
    VideoBox.SetSource(stream, file.ContentType);
    VideoBox.Stop();
    VideoBox.Play();
}
else
{
    // TODO: No file selected. Handle the error here.
}