Expand Minimize

StorageFolder.CreateFolderQueryWithOptions | createFolderQueryWithOptions method

Applies to Windows only

Gets a query result object that contains the subfolders in the current folder and, optionally, nested subfolders. The results are based on the specified QueryOptions.

Syntax


public:
StorageFolderQueryResult^ CreateFolderQueryWithOptions(
  QueryOptions^ queryOptions
)

Parameters

queryOptions

Type: QueryOptions

The criteria that are applied to the query.

Return value

Type: StorageFolderQueryResult

A query result object. Call the GetFoldersAsync method of the query result to get the subfolders in the current folder. If you provided a CommonFolderQuery value other than CommonFolderQuery.DefaultQuery when you instantiated the QueryOptions, 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 queryOptions. 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.UnauthorizedAccessException

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

Remarks

In the following cases, this query is a shallow query that returns only subfolders in the current folder.

  • Default behavior of this method if none of the following options are specified.

    - or -

  • Specify DefaultQuery as the value of CommonFolderQuery when you instantiate the QueryOptions object.

    - or -

  • Specify Shallow as the value of the FolderDepth property of the QueryOptions object.

In the following cases, this query is a deep query that returns subfolders in the current folder and nested subfolders.

Note  

Values other than DefaultQuery from the CommonFolderQuery enumeration can only be used with a library folder (such as the Pictures library) or the Homegroup folder.

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

To check whether the QueryOptions you want to specify are available for the current folder, call the folder's AreQueryOptionsSupported method. 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 get a query result object that contains the subfolders in the current folder without configuring a QueryOptions object, call one of the CreateFolderQuery methods.

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

For Windows Server 2012:  You must install indexer components to use some QueryOptions, CommonFileQuery values, and 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 CreateFolderQueryWithOptions(QueryOptions) method. (Files from the root of the current folder are not included.) This query is a deep query because the folder is a library folder and a value other than DefaultQuery from the CommonFolderQuery enumeration is specified.

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


	// Get user's pictures folder
	StorageFolder^ picturesFolder = KnownFolders::PicturesLibrary;

	QueryOptions^ options = ref new QueryOptions(CommonFolderQuery::GroupByMonth);

	// Get the files in the user's Pictures folder and group them by month
	StorageFolderQueryResult^ itemsInFolder = picturesFolder->CreateFolderQueryWithOptions(QueryOptions);

	create_task(itemsInFolder->GetFoldersAsync()).then([=](IVectorView<StorageFolder^>^ itemsInFolder) {
		//Iterate over the results and print the list of file groups
		// to the visual studio output window
		for (auto it = itemsInFolder->First(); it->HasCurrent; it->MoveNext())
		{
			StorageFolder^ file = it->Current;
			String^ output = file->Name + "\n";
			OutputDebugString(output->Begin());
		}
	});


Requirements

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

 

 

Show:
© 2014 Microsoft