홈 그룹 콘텐츠 액세스Accessing HomeGroup content

중요 APIImportant APIs

사진, 음악, 동영상 등 사용자의 홈 그룹 폴더에 저장된 콘텐츠에 액세스합니다.Access content stored in the user's HomeGroup folder, including pictures, music, and videos.

필수 구성 요소Prerequisites

  • UWP(유니버설 Windows 플랫폼) 앱에 대한 비동기 프로그래밍 이해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

    홈 그룹 콘텐츠에 액세스하려면 사용자의 컴퓨터에 홈 그룹이 설정되어 있고 앱에는 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를 사용하여 파일 선택기를 만든 다음 선택기의 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.

    파일 선택기를 만들어 사용자 지정한 후 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.

    여기서는 사용자가 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.

    홈 그룹에 있는 각각의 첫 번째 수준 폴더는 개별 홈 그룹 사용자를 나타냅니다.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.
    }