StorageFolder.GetFoldersAsync(CommonFolderQuery, UInt32, UInt32) | getFoldersAsync(CommonFolderQuery, UInt32, UInt32) method

Applies to Windows and Windows Phone

Gets an index-based range of folders from the list of all subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, gets a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. Files are grouped into folders based on the specified value from the CommonFolderQuery enumeration.

Syntax


storageFolder.getFoldersAsync(query, startIndex, maxItemsToRetrieve).done( /* Your success and error handlers */ );

Parameters

query

Type: CommonFolderQuery

One of the enumeration values that specifies how to group the files into folders and determines whether the query is shallow or deep.

startIndex

Type: Number [JavaScript] | System.UInt32 [.NET] | uint32 [C++]

The zero-based index of the first folder in the range to retrieve.

maxItemsToRetrieve

Type: Number [JavaScript] | System.UInt32 [.NET] | uint32 [C++]

The maximum number of folders to retrieve.

Return value

Type: IAsyncOperation<IVectorView>

When this method completes successfully, it returns a list of subfolders. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, this method returns a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. (Files from the current folder are not included.) The files are grouped as specified by query. The list is of type IReadOnlyList<StorageFolder>. Each folder in the list is represented by a StorageFolder object.

Exceptions

ExceptionCondition
System.UnauthorizedAccessException

You don't have permission to access the contents of the current folder.

Remarks

A CommonFolderQuery groups the contents of subfolders into folders based on specific file attributes (like artist or album) quickly and easily. You can use the DefaultQuery option with any folder; you can use the other options only with library folders, such as the Pictures library, or the Homegroup folder.

When you specify the DefaultQuery option from the CommonFolderQuery enumeration, this query is a shallow query that returns only subfolders in the current folder. When you specify another value from the CommonFolderQuery enumeration, this query is a deep query that groups the contents of subfolders of the current folder into virtual folders. (Files from the current folder are not included.) For example, if you specify GroupByMonth, the query returns a list of virtual folders such as July 2014, August 2014, and September 2014.

For a list of methods that identifies shallow queries and deep queries, see the Remarks in the topic GetFoldersAsync.

To get deep query results from a folder that's not a library folder, call the CreateFileQueryWithOptions(QueryOptions) method and specify Deep as the value of the FolderDepth property of the QueryOptions.

To check whether a specific CommonFolderQuery is available, call the folder's IsCommonFolderQuerySupported method.

To specify additional query options, call the CreateFolderQueryWithOptions method.

To get items that are files or folders, call the GetItemsAsync method.

Examples

The following example shows how to get the contents of the subfolders in the user's Pictures folder, grouped by month, by calling the GetFoldersAsync(CommonFolderQuery, UInt32, UInt32) method. (Files from the root of the current folder are not included.) This example returns a maximum of 4 folders, starting with the folder at index 0. Since the CommonFolderQuery.GroupByMonth option sorts dates in descending order (that is, from newest to oldest), this example returns folders for the 4 most recent months for which the user has photos. Each folder contains all the user's photos from that month.

Before you run the following example, enable the Pictures Library capability in the app manifest file.


using Windows.Storage;
using Windows.Storage.Search;
using System.Threading.Tasks;
using System.Diagnostics; // For writing results to Output window.
...
            // Get the user's Pictures folder.
            // Enable the corresponding capability in the app manifest file.
            StorageFolder picturesFolder = KnownFolders.PicturesLibrary;

            // Get the files in the subfolders of the user's Pictures folder,
            // grouped by month. Get only the first 4 folders (months).
            IReadOnlyList <StorageFolder> groupedItems =
                     await picturesFolder.GetFoldersAsync(CommonFolderQuery.GroupByMonth, 0, 4);

            // Iterate over the results and print the list of folders
            // and files to the Visual Studio Output window.
            foreach (StorageFolder folder in groupedItems)
            {
                Debug.WriteLine(folder.Name);

                // To iterate over the files in each folder,
                // uncomment the following lines.
                // foreach(StorageFile file in await folder.GetFilesAsync())
                //    Debug.WriteLine(" " + file.Name);
            }


Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8

Namespace

Windows.Storage
Windows::Storage [C++]

Metadata

Windows.winmd

See also

StorageFolder
GetFoldersAsync(CommonFolderQuery)
GetFoldersAsync
GetItemsAsync

 

 

Show:
© 2014 Microsoft