ホームグループ コンテンツへのアクセスAccessing HomeGroup content

重要な APIImportant APIs

ユーザーのホームグループ フォルダーに格納されているコンテンツ (画像、音楽、ビデオなど) にアクセスします。Access content stored in the user's HomeGroup folder, including pictures, music, and videos.

前提条件Prerequisites

  • ユニバーサル Windows プラットフォーム (UWP) アプリの非同期プログラミングについての理解Understand async programming for Universal Windows Platform (UWP) apps

    C# や Visual Basic での非同期アプリの作成方法については、「C# または Visual Basic での非同期 API の呼び出し」をご覧ください。You can learn how to write asynchronous apps in C# or Visual Basic, see Call asynchronous APIs in C# or Visual Basic. C++ での非同期アプリの作成方法については、「C++ での非同期プログラミング」をご覧ください。To learn how to write asynchronous apps in C++, see Asynchronous programming in C++.

  • アプリ機能の宣言App capabilty declarations

    ホームグループ コンテンツにアクセスするには、ユーザーのコンピューターにホームグループがセットアップされ、アプリに picturesLibrarymusicLibraryvideosLibrary のうちの少なくとも 1 つの機能が備わっている必要があります。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.

    注意

     ホームグループのドキュメント ライブラリのコンテンツは、アプリのマニフェストで宣言されている機能や、ユーザーの共有設定にかかわらず、アプリからは参照できません。 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:

  1. ファイル ピッカーを作成してカスタマイズします。Create and customize the file picker

    FileOpenPicker を使ってファイル ピッカーを作成し、ピッカーの SuggestedStartLocationPickerLocationId.HomeGroup に設定します。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("*");
    
  2. ファイル ピッカーを表示して、選ばれたファイルを処理します。Show the file picker and process the picked file.

    ファイル ピッカーを作成してカスタマイズしたら、ユーザーが 1 つのファイルを選べるように FileOpenPicker.PickSingleFileAsync を呼び出すか、複数のファイルを選べるように FileOpenPicker.PickMultipleFilesAsync を呼び出します。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.

    次の例では、ファイル ピッカーを表示して、ユーザーが 1 つのファイルを選べるようにしています。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.

  1. ユーザーからクエリ語句を取得します。Get the query term from the user.

    ここでは、ユーザーが searchQueryTextBox という名前の TextBox コントロールに入力したクエリ語句を取得します。Here we get a query term that the user has entered into a TextBox control called searchQueryTextBox:

    string queryTerm = this.searchQueryTextBox.Text;    
    
  2. クエリ オプションと検索フィルターを設定します。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);    
    
  3. クエリを実行し、結果を処理します。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.

  1. ホームグループ ユーザーのコレクションを取得します。Get a collection of HomeGroup users.

    ホームグループの第 1 レベルのフォルダーは、それぞれが個々のホームグループ ユーザーを表しています。Each of the first-level folders in the HomeGroup represents an individual HomeGroup user. そのため、ホームグループ ユーザーのコレクションを取得するには、GetFoldersAsync を呼び出し、第 1 レベルのホームグループ フォルダーを取得します。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();    
    
  2. 目的のユーザーのフォルダーを見つけ、そのユーザーのフォルダーをスコープにしたファイル クエリを作成します。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:

  1. アプリに MediaElement を含めます。Include a MediaElement in your app.

    MediaElement は、アプリのオーディオ コンテンツとビデオ コンテンツを再生します。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>    
    
  2. ファイル ピッカーをホームグループで開き、アプリでサポートされている形式のビデオ ファイルを含めるフィルターを適用します。Open a file picker at the HomeGroup and apply a filter that includes video files in the formats that your app supports.

    次の例では、ファイル オープン ピッカーに .mp4 ファイルと .wmv ファイルが含まれます。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();   
    
  3. ユーザーが選んだファイルを読み取りアクセスで開き、ファイル ストリームを MediaElement のソースとして設定して、ファイルを再生します。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.
    }