StorageFileQueryResult StorageFileQueryResult StorageFileQueryResult StorageFileQueryResult Class

Definition

Provides access to the results of a query of the files in the location that is represented by a storageFolder object. You can use storageFileQueryResult to enumerate the files in that storageFolder location.

public : sealed class StorageFileQueryResult : IStorageFileQueryResult, IStorageFileQueryResult2, IStorageQueryResultBase
public sealed class StorageFileQueryResult : IStorageFileQueryResult, IStorageFileQueryResult2, IStorageQueryResultBase
Public NotInheritable Class StorageFileQueryResult Implements IStorageFileQueryResult, IStorageFileQueryResult2, IStorageQueryResultBase
// This class does not provide a public constructor.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

This example demonstrates how to get a list of files from a storageFileQueryResult object.

// Set query options with filter and sort order for results
List<string> fileTypeFilter = new List<string>();
fileTypeFilter.Add(".jpg");
fileTypeFilter.Add(".png");
fileTypeFilter.Add(".bmp");
fileTypeFilter.Add(".gif");
var queryOptions = new QueryOptions(CommonFileQuery.OrderByName, fileTypeFilter);

// Create query and retrieve files
var query = KnownFolders.PicturesLibrary.CreateFileQueryWithOptions(queryOptions);
IReadOnlyList<StorageFile> fileList = await query.GetFilesAsync();
// Process results
foreach (StorageFile file in fileList)
{
    // Process file
}

// Set query options with filter and sort order for results
var fileTypeFilter = [".jpg", ".png", ".bmp", ".gif"];
var queryOptions = new Windows.Storage.Search.QueryOptions(search.CommonFileQuery.orderByName, fileTypeFilter);

// Create query and retrieve files
var query = Windows.Storage.KnownFolders.picturesLibrary.createFileQueryWithOptions(queryOptions);
query.getFilesAsync().done(function (files) {
    // Process results
    files.forEach(function (file) {
        // Process file
    });
});

The query variable gets the storageFileQueryResult that is used to retrieve files that meet the criteria of the query.

Note

You need the Pictures library capability to access the library using KnownFolders.PicturesLibrary. To learn more about capabilities and file access, see File access permissions.

Remarks

Note

Although it's not attributed with marshalling_behavior(agile), this class can be treated as agile.

You can get a storageFileQueryResult object by calling the following methods from a storageFolder or a folderInformation object:

Properties

Folder Folder Folder Folder

Gets the folder that was queried to create the StorageFileQueryResult object. This folder represents the scope of the query.

public : StorageFolder Folder { get; }
public StorageFolder Folder { get; }
Public ReadOnly Property Folder As StorageFolder
var storageFolder = storageFileQueryResult.folder;

Methods

ApplyNewQueryOptions(QueryOptions) ApplyNewQueryOptions(QueryOptions) ApplyNewQueryOptions(QueryOptions) ApplyNewQueryOptions(QueryOptions)

Modifies query results based on new QueryOptions.

public : void ApplyNewQueryOptions(QueryOptions newQueryOptions)
public void ApplyNewQueryOptions(QueryOptions newQueryOptions)
Public Function ApplyNewQueryOptions(newQueryOptions As QueryOptions) As void
storageFileQueryResult.applyNewQueryOptions(newQueryOptions);
Parameters
newQueryOptions
QueryOptions QueryOptions QueryOptions QueryOptions

The new query options.

Remarks

This method causes the OptionsChanged event to fire.

When this method returns, subsequent calls to GetFilesAsync or GetItemCountAsync will reflect the results of the new QueryOptions.

FindStartIndexAsync(Object) FindStartIndexAsync(Object) FindStartIndexAsync(Object) FindStartIndexAsync(Object)

Retrieves the index of the file from the query results that most closely matches the specified property value (or file, if used with FileActivatedEventArgs.NeighboringFilesQuery ). The property that is matched is determined by the first SortEntry of the QueryOptions.SortOrder list.

public : IAsyncOperation<unsigned int> FindStartIndexAsync(Platform::Object value)
public IAsyncOperation<uint> FindStartIndexAsync(Object value)
Public Function FindStartIndexAsync(value As Object) As IAsyncOperation( Of uint )
Windows.Storage.Search.StorageFileQueryResult.findStartIndexAsync(value).done( /* Your success and error handlers */ );
Parameters
value
Platform::Object Object Object Object

The property value to match when searching the query results. The property to that is used to match this value is the property in the first SortEntry of the QueryOptions.SortOrder list.

Or, the file to match when searching with FileActivatedEventArgs.NeighboringFilesQuery.

Returns

When this method completes successfully, it returns the index of the matched file in the query results or the index of the file in the FileActivatedEventArgs.NeighboringFilesQuery. In the latter case, the file is expected to be sourced from FileActivatedEventArgs.Files. If this function fails, it returns uint.MaxValue.

Examples

This example shows how to find the first song in an album that has a title beginning with the "R" in a set of query results that contains songs grouped by album title.


QueryOptions queryOptions = new QueryOptions();
queryOptions.FolderDepth = FolderDepth.Deep;
queryOptions.IndexerOption = IndexerOption.OnlyUseIndexer;
SortEntry album = new SortEntry();
album.AscendingOrder = true;
album.PropertyName = "System.Music.AlbumTitle";
queryOptions.SortOrder.Add(album);

StorageFileQueryResult queryResult = musicFolder.CreateFileQueryWithOptions(queryOptions);
var firstIndex = await queryResult.FindStartIndexAsync("R");
var queryOptions = new Windows.Storage.Search.QueryOptions();
queryOptions.folderDepth = Windows.Storage.Search.FolderDepth.deep;
queryOptions.indexerOption = Windows.Storage.Search.IndexerOptions.onlyUseIndexer;
queryOptions.sortOrder.append({
 ascendingOrder: true,
 propertyName: "System.Music.AlbumTitle"
});

var queryResult = Windows.Storage.KnownFolders.picturesLibrary.createFileQueryWithOptions(queryOptions);
var firstIndex = queryResult.findStartIndexAsync("R");

Remarks

You can use this method in conjunction with FileActivatedEventArgs.NeighboringFilesQuery to iterate between neighboring files while preserving the original view's sort order.

GetCurrentQueryOptions() GetCurrentQueryOptions() GetCurrentQueryOptions() GetCurrentQueryOptions()

Retrieves the query options used to determine query results.

public : QueryOptions GetCurrentQueryOptions()
public QueryOptions GetCurrentQueryOptions()
Public Function GetCurrentQueryOptions() As QueryOptions
var queryOptions = storageFileQueryResult.getCurrentQueryOptions();
Returns

GetFilesAsync() GetFilesAsync() GetFilesAsync() GetFilesAsync()

Retrieves a list of all the files in the query result set.

public : IAsyncOperation<IVectorView<StorageFile>> GetFilesAsync()
public IAsyncOperation<IReadOnlyList<StorageFile>> GetFilesAsync()
Public Function GetFilesAsync() As IAsyncOperation<IReadOnlyList<StorageFile>>( Of IVectorView )
Windows.Storage.Search.StorageFileQueryResult.getFilesAsync().done( /* Your success and error handlers */ );
Returns
IAsyncOperation<IVectorView<StorageFile>> IAsyncOperation<IReadOnlyList<StorageFile>> IAsyncOperation<IReadOnlyList<StorageFile>> IAsyncOperation<IReadOnlyList<StorageFile>>

When this method completes successfully, it returns a list (type IVectorView ) of files that are represented by storageFile objects.

See Also

GetFilesAsync(UInt32, UInt32) GetFilesAsync(UInt32, UInt32) GetFilesAsync(UInt32, UInt32) GetFilesAsync(UInt32, UInt32)

Retrieves a list of files in a specified range.

public : IAsyncOperation<IVectorView<StorageFile>> GetFilesAsync(unsigned int startIndex, unsigned int maxNumberOfItems)
public IAsyncOperation<IReadOnlyList<StorageFile>> GetFilesAsync(UInt32 startIndex, UInt32 maxNumberOfItems)
Public Function GetFilesAsync(startIndex As UInt32, maxNumberOfItems As UInt32) As IAsyncOperation<IReadOnlyList<StorageFile>>( Of IVectorView )
Windows.Storage.Search.StorageFileQueryResult.getFilesAsync(startIndex, maxNumberOfItems).done( /* Your success and error handlers */ );
Parameters
startIndex
unsigned int UInt32 UInt32 UInt32

The zero-based index of the first file to retrieve. This parameter is 0 by default.

maxNumberOfItems
unsigned int UInt32 UInt32 UInt32

The maximum number of files to retrieve. Use -1 to retrieve all files. If the range contains fewer files than the max number, all files in the range are returned.

Returns
IAsyncOperation<IVectorView<StorageFile>> IAsyncOperation<IReadOnlyList<StorageFile>> IAsyncOperation<IReadOnlyList<StorageFile>> IAsyncOperation<IReadOnlyList<StorageFile>>

When this method completes successfully, it returns a list (type IVectorView ) of files that are represented by storageFile objects.

Remarks

Use this overload to improve system performance by presenting a virtualized view of the query results that includes only the necessary subset of files. For example, if your app displays many files in a gallery you could use this range to retrieve only the files that are currently visible to the user.

See Also

GetItemCountAsync() GetItemCountAsync() GetItemCountAsync() GetItemCountAsync()

Retrieves the number of files in the set of query results.

public : IAsyncOperation<unsigned int> GetItemCountAsync()
public IAsyncOperation<uint> GetItemCountAsync()
Public Function GetItemCountAsync() As IAsyncOperation( Of uint )
Windows.Storage.Search.StorageFileQueryResult.getItemCountAsync().done( /* Your success and error handlers */ );
Returns

When this method completes successfully, it returns the number of files in the location that match the query.

See Also

GetMatchingPropertiesWithRanges(StorageFile) GetMatchingPropertiesWithRanges(StorageFile) GetMatchingPropertiesWithRanges(StorageFile) GetMatchingPropertiesWithRanges(StorageFile)

Gets matching file properties with corresponding text ranges.

public : IMap<Platform::String, IVectorView<TextSegment>> GetMatchingPropertiesWithRanges(StorageFile file)
public IDictionary<string, IReadOnlyList<TextSegment>> GetMatchingPropertiesWithRanges(StorageFile file)
Public Function GetMatchingPropertiesWithRanges(file As StorageFile) As IDictionary<string, IReadOnlyList<TextSegment>>( Of string )( Of IVectorView )
var iMap = storageFileQueryResult.getMatchingPropertiesWithRanges(file);
Parameters
file
StorageFile StorageFile StorageFile StorageFile

The file to query for properties.

Returns
IMap<Platform::String, IVectorView<TextSegment>> IDictionary<string, IReadOnlyList<TextSegment>> IDictionary<string, IReadOnlyList<TextSegment>> IDictionary<string, IReadOnlyList<TextSegment>>

The matched properties and corresponding text ranges.

Remarks

Use this method to implement hit highlighting in your app's query results.

Events

ContentsChanged ContentsChanged ContentsChanged ContentsChanged

Fires when a file is added to, deleted from, or modified in the folder being queried. This event only fires after GetFilesAsync has been called at least once.

public : event TypedEventHandler ContentsChanged<IStorageQueryResultBase, object>
public event TypedEventHandler ContentsChanged<IStorageQueryResultBase, object>
Public Event TypedEventHandler ContentsChanged( Of ( Of IStorageQueryResultBase ), ( Of object ))
function onContentsChanged(eventArgs){/* Your code */}


storageFileQueryResult.addEventListener("contentsChanged", onContentsChanged);
storageFileQueryResult.removeEventListener("contentsChanged", onContentsChanged);

Remarks

If you register a handler for this event, keep that handler registered while you suspend your app (in response to oncheckpoint or Suspending ). Your app will not receive ContentsChanged events while it is suspended and when your app resumes it will receive a single event that aggregates all of the changes if any occurred.

Additionally, keep in mind that registering and removing event handlers are synchronous operations and might cause your app to stop responding briefly if you execute them on your app's UI thread. Wherever possible, use a thread other than your app's UI thread to register and unregister these event handlers.

OptionsChanged OptionsChanged OptionsChanged OptionsChanged

Fires when the query options change.

public : event TypedEventHandler OptionsChanged<IStorageQueryResultBase, object>
public event TypedEventHandler OptionsChanged<IStorageQueryResultBase, object>
Public Event TypedEventHandler OptionsChanged( Of ( Of IStorageQueryResultBase ), ( Of object ))
function onOptionsChanged(eventArgs){/* Your code */}


storageFileQueryResult.addEventListener("optionsChanged", onOptionsChanged);
storageFileQueryResult.removeEventListener("optionsChanged", onOptionsChanged);

See Also