Доступ к содержимому домашней группы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 см. в статье Вызов асинхронных API в C# и Visual Basic.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

    Для получения доступа к содержимому домашней группы на компьютере пользователя должна быть настроена домашняя группа, а ваше приложение должно поддерживать по крайней мере одну из следующих возможностей: picturesLibrary, musicLibrary или videosLibrary.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, чтобы создать средство выбора файлов, и задайте для его свойства SuggestedStartLocation значение PickerLocationId.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.

    После создания и настройки средства выбора файлов пользователь может выбрать один файл, вызвав 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.

    Этот пример отображает средство выбора файлов, чтобы позволить пользователю выбрать один файл.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.

    Вот термин запроса, который пользователь ввел в элемент управления TextBox, называемый searchQueryTextBox: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.

    Каждая из папок первого уровня в домашней группе представляет отдельного пользователя домашней группы.Each of the first-level folders in the HomeGroup represents an individual HomeGroup user. Поэтому, чтобы получить коллекцию пользователей домашней группы, вызовите GetFoldersAsync и получите папки домашней группы верхнего уровня.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.
    }