StorageFolder.GetFilesAsync(CommonFileQuery, UInt32, UInt32) | getFilesAsync(CommonFileQuery, UInt32, UInt32) method

Applies to Windows and Windows Phone

Gets an index-based range of files from the list of all files in the current folder. Also gets the files from the subfolders of the current folder when the value of the query argument is something other than CommonFileQuery.DefaultQuery. Files are sorted based on the specified value from the CommonFileQuery enumeration.

Syntax


public:
IAsyncOperation<IVectorView>^ GetFilesAsync(
  CommonFileQuery query, 
  unsigned int startIndex, 
  unsigned int maxItemsToRetrieve
)

Parameters

query

Type: CommonFileQuery

One of the enumeration values that specifies how to sort the files 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 file in the range to retrieve.

maxItemsToRetrieve

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

The maximum number of files to retrieve.

Return value

Type: IAsyncOperation<IVectorView>

When this method completes successfully, it returns a flat list of files sorted as specified by query. The list is of type IReadOnlyList<StorageFile>. Each file in the list is represented by a StorageFile object.

Exceptions

ExceptionCondition
System.UnauthorizedAccessException

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

Remarks

A CommonFileQuery sorts files based on specific file attributes (like title or date) quickly and easily.

When you specify the DefaultQuery option from the CommonFileQuery enumeration, this query is a shallow query that returns only files in the current folder. When you specify another value from the CommonFileQuery enumeration, this query is a deep query that returns a flattened list of files from the current folder and from its subfolders.

Note  

Some of the values from the CommonFileQuery enumeration can only be used with a library folder (such as the Pictures library) or the Homegroup folder. In addition to the DefaultQuery option, you can use only the OrderByName and OrderBySearchRank options with a folder that's not a library folder.

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.

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

To check whether a specific CommonFileQuery is available, call the folder's IsCommonFileQuerySupported method.

To specify additional query options, call the CreateFileQueryWithOptions 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 user's Pictures folder and its subfolders, sorted by date, by calling the GetFilesAsync(CommonFileQuery, UInt32, UInt32) method. This example returns a maximum of 20 files, starting with the file at index 0. Since the CommonFileQuery.OrderByDate option sorts dates in descending order (that is, from newest to oldest), this example returns the user's 20 most recent photos.

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


	// Get user's pictures library
	StorageFolder^ picturesLibrary = KnownFolders::PicturesLibrary;

	// Get the first 20 sorted images in the library
	create_task(picturesLibrary->GetFilesAsync(CommonFileQuery::OrderByDate,0,20)).then([=](IVectorView<StorageFile^>^ filesInFolder) {
		//Iterate over the results and print the list of files
		// to the visual studio output window
		for (auto it = filesInFolder->First(); it->HasCurrent; it->MoveNext())
		{
			StorageFile^ 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

Windows Phone 8

Namespace

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

Metadata

Windows.winmd

See also

StorageFolder
GetFilesAsync(CommonFileQuery)
GetFilesAsync
GetItemsAsync

 

 

Show:
© 2014 Microsoft