Accessing HomeGroup content

Article
10/20/2022

Important APIs

Windows.Storage.KnownFolders class

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

Prerequisites

Understand async programming for Universal Windows Platform (UWP) apps

You can learn how to write asynchronous apps in C# or Visual Basic, see Call asynchronous APIs in C# or Visual Basic. To learn how to write asynchronous apps in C++, see Asynchronous programming in C++.
App capability 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: picturesLibrary, musicLibrary, or videosLibrary. When your app accesses the HomeGroup folder, it will see only the libraries that correspond to the capabilities declared in your app's manifest. To learn more, see File access permissions.

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 Open files and folders with a picker.
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 Enumerating and querying files and folders.

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)
{
    // Do something with the file.
}
else
{
    // 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 searchQueryTextBox:
```
string queryTerm = this.searchQueryTextBox.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 Create custom transport controls and Audio, video, and camera.

<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 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
{
    // No file selected. Handle the error here.
}