StorageFolder.CreateFolderQuery(CommonFolderQuery) | createFolderQuery(CommonFolderQuery) method

Gets a query result object that contains the 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


var storageFolderQueryResult = storageFolder.createFolderQuery(query);

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.

Return value

Type: StorageFolderQueryResult

A query result object. Call the GetFoldersAsync method of the query result to get the subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, the query result object contains 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.

System.ArgumentException

You specified a value other than DefaultQuery from the CommonFolderQuery enumeration for a folder that's not a library folder. Check the value of query.

Remarks

A CommonFolderQuery groups the contents of subfolders into folders based on specific file attributes (like artist or album) quickly and easily.

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.

Note  

You can use the DefaultQuery option with any folder; you can use the other options from the CommonFolderQuery enumeration only with library folders, such as the Pictures library, or the Homegroup folder.

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

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

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

You can also get a list of subfolders in the current folder asynchronously by calling one of the GetFoldersAsync methods.

To specify additional query options, call the CreateFolderQueryWithOptions method.

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

For Windows Server 2012:  You must install indexer components to use some CommonFolderQuery values because indexer components are not installed by default.

Examples

The following example shows how to get the contents of the subfolders in the user's Pictures folder, grouped into folders by month, by calling the GetFoldersAsync(CommonFolderQuery) method. (Files from the root of the current folder are not included.)

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


// Get the user's Pictures folder.
// Enable the corresponding capability in the app manifest file.
var KnownFolders = Windows.Storage.KnownFolders;
var picturesFolder = KnownFolders.picturesLibrary;

// Get the JPG files in the user's Pictures folder and group them by month.
var CommonFolderQuery = Windows.Storage.Search.CommonFolderQuery;
var groupedItems = picturesFolder.createFolderQuery(CommonFolderQuery.groupByMonth);

// Iterate over the results and print the list of folders
// and files to the Visual Studio Output window.
var subfoldersPromise = groupedItems.getFoldersAsync();
subfoldersPromise.done(function getFoldersSuccess(subfolders) {
    subfolders.forEach(function forEachSubfolder(folder) {
        console.log(folder.name);

        // To iterate over the files in each folder,
        // uncomment the following lines.
        // var filesPromise = folder.getFilesAsync();
        // filesPromise.done(function (files) {
        //     console.log(folder.name);
        //     files.forEach(function forEachFile(file) {
        //         console.log(".", file.name);
        //     });
        // });
    });
});

Requirements (device family)

Device family

Universal

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

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

Metadata

Windows.Foundation.UniversalApiContract.winmd

Requirements (operating system)

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

None supported

Namespace

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

Metadata

Windows.winmd

See also

StorageFolder
CreateFolderQuery

 

 

Show:
© 2015 Microsoft