Quickstart: Accessing HomeGroup content (HTML)

Article
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 JavaScript

You can learn how to write asynchronous apps in Quickstart: Using promises in JavaScript.
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 that you declared in your app's manifest. Learn more about these capabilities in App capability declarations.

Note Content in the Documents folder 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.
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. Also, 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:
```
var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.homeGroup;
picker.fileTypeFilter.replaceAll(["*"]);
picker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```

Show the file picker.

After you create and customize the file picker, let the user pick one file by calling fileOpenPicker.pickSingleFileAsync. Or, let them pick multiple files by calling fileOpenPicker.pickMultipleFilesAsync.

This example shows how to display the file picker to let the user pick one file, and how to capture the picked file for processing:

picker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // The app now has read/write access to the picked file.
        WinJS.log && WinJS.log("1 file selected: \"" + file.path + "\"", 
            "sample", "status");

        // If the returned file was an image, show it to the user.
        if ((".JPG" === file.fileType) || (".jpg" === file.fileType) || 
            (".JPEG" === file.fileType) || (".jpeg" === file.fileType) || 
            (".PNG" === file.fileType) || (".png" === file.fileType) || 
            (".BMP" === file.fileType) || (".bmp" === file.fileType)) {
                document.getElementById("returnedImage").src = 
                    URL.createObjectURL(file, { oneTimeOnly: true });
                document.getElementById("returnedImage").style.visibility = "visible";
        } else {
            // The returned file wasn't an image, so hide the container where it 
            // would have appeared.
            document.getElementById("returnedImage").style.visibility = "hidden";
        }
    }
},

function (file) {
    // An error occurred.
    WinJS.log && WinJS.log("File was not returned", "sample", "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 an input field:
```
var query = document.getElementById("queryString").value;
```

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:

var options = new Windows.Storage.Search.QueryOptions(
    Windows.Storage.Search.CommonFileQuery.orderBySearchRank, ["*"]);
options.userSearchFilter = query;

Run the query and process the results.

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

try {
    var queryResult = 
        Windows.Storage.KnownFolders.homeGroup.createFileQueryWithOptions(options);

    queryResult.getFilesAsync().then(function (files) {
        // If no matching files were found, show appropriate output and turn 
        // off the progress ring.
        if (files.size === 0) {
            WinJS.log && WinJS.log("No files found for \"" + query + "\"", 
                "sample", "status");
            document.getElementById("searchProgress").style.visibility = "hidden";
        }

        // We found matching files. Show them and turn off the progress ring.
        else {
            var outputString = (files.size === 1) ? 
                (files.size + " file found\n") : (files.size + " files found\n");
            files.forEach(function (file) {
                outputString = outputString.concat(file.name, "\n");
            });
            WinJS.log && WinJS.log(outputString, "sample", "status");
            document.getElementById("searchProgress").style.visibility = "hidden";
        }
    });
}
catch (e) {
    // An error occurred. Show and log the error.
    document.getElementById("searchProgress").style.visibility = "hidden";
    WinJS.log && WinJS.log(e.message, "sample", "error");
}

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 represent an individual HomeGroup user. So, to get the collection of HomeGroup users, call GetFoldersAsync retrieve the top-level HomeGroup folders, and then iterate through the retrieved folders to get the individual users.
```
var hg = Windows.Storage.KnownFolders.homeGroup;
hg.getFoldersAsync().then(function (users) {
    users.forEach(function (user) {

    // TODO: Do something with the user name. 

    });
}
```
Create a file query and scope it to a particular user.

The following example sets query options to sort the search results first by relevance, and then by the date modified. The query options are then applied to a search query that is scoped to a particular user.
```
var options = new Windows.Storage.Search.QueryOptions(
    Windows.Storage.Search.CommonFileQuery.orderBySearchRank, ["*"]);
var query = user.createFileQueryWithOptions(options);
```

Run the query and process the resulting files.

This example runs the search query and saves the names of the files that match the particular user, as a list of strings.

query.getFilesAsync().then(function (files) {

    // If we don't find any shared files for the specified user, 
    // hide the progress indicator and notify the user. 
    if (files.size === 0) {
        document.getElementById("searchProgress").style.visibility = "hidden";

        // In the following line, userToSearch is a name specified by
        // the app user.
        outputString = "No files shared by " + userToSearch + ""; 
    }

    // We found shared files for this user. Hide the progress indicator
    // and process the files.  
    else {
        document.getElementById("searchProgress").style.visibility = "hidden";
        outputString = (files.size === 1) ? 
            (files.size + " file found\n") : (files.size + " files shared by ");
        outputString = outputString.concat(userToSearch, "\n");
        files.forEach(function (file) {
            outputString = outputString.concat(file.name, "\n");
        });
    }
});

Stream video from the HomeGroup

Follow these steps to stream video content from the HomeGroup:

Include a video element in an app HTML page.

The video element specifies video content to be played in your app.

<div data-win-control="SdkSample.ScenarioOutput">
    <video id="player" height="338" width="600" controls style="visibility: hidden">Unable to play video file</video>
</div>

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.

var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
picker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.homeGroup;
picker.fileTypeFilter.replaceAll([".mp4", ".wmv"]);

Convert the user's file selection to a URL, and set the URL as the source for the video element.

The following example retrieves the video element and initializes it to be invisible and in the paused state. After the user chooses a video file, the example retrieves the URL of the file, sets it as the source for the video element, shows the video element, and starts playing the video.

var vidPlayer = document.getElementById("player");
vidPlayer.style.visibility = "hidden";
vidPlayer.pause();
picker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // The video tag has built in capabilities to stream the video over 
        // the network.
        vidPlayer.src = URL.createObjectURL(file, { oneTimeOnly: true });
        vidPlayer.style.visibility = "visible";
        vidPlayer.play();
    }
},
function (file) {
    WinJS.log && WinJS.log("File was not returned", "sample", "error");
});