Share via

IStorageProviderSuggestionsHandler.GetSuggestions Method

Definition

Namespace:
Windows.Storage.Provider
Edit

Executes the suggestions query given the parameters in the options object and returns a result set.

Important

The Windows.Storage.Provider.IStorageProviderSuggestionsHandler API is part of a Limited Access Feature (see LimitedAccessFeatures class). For more information or to request an unlock token, please use the LAF Access Token Request Form.

public:
 StorageProviderQueryResultSet ^ GetSuggestions(StorageProviderSuggestionsQueryOptions ^ options);
StorageProviderQueryResultSet GetSuggestions(StorageProviderSuggestionsQueryOptions const& options);
public StorageProviderQueryResultSet GetSuggestions(StorageProviderSuggestionsQueryOptions options);
function getSuggestions(options)
Public Function GetSuggestions (options As StorageProviderSuggestionsQueryOptions) As StorageProviderQueryResultSet

Parameters

options
StorageProviderSuggestionsQueryOptions

The options used to customize the suggestions query.

Returns

StorageProviderQueryResultSet

The result set object that contains the list of results.

Examples

The following is an example of how a cloud storage provider could implement GetSuggestions to return recent files by parsing a JSON response returned from a cloud storage service:

constexpr auto c_sampleSuggestionsResponse =
    LR"({
        "suggestionsKind": "Recent",
        "results": [
            {
                "filePath": "C:\Users\UserA\ContosoDrive\foo.txt",
                "id": "11",
                "requestedProperties": {
                    "System.ItemNameDisplayWithoutExtension": "foo",
                    "System.FileExtension": ".txt",
                    "System.ContentUri": "https://contoso.com/UserA/foo.txt",
                    "System.DateAccessed": "2020-01-01T12:00:00Z"
                }
            },
            {
                "filePath": "",
                "id": "12",
                "requestedProperties": {
                    "System.ItemNameDisplayWithoutExtension": "bar",
                    "System.FileExtension": ".txt",
                    "System.ContentUri": "https://contoso.com/UserB/bar.txt",
                    "System.DateAccessed": "2020-01-01T12:00:00Z"
                }
            }
        ]
    })";

std::vector<StorageProviderSuggestionResult> ParseSuggestionResponse(IVectorView<hstring> propertiesToFetch)
{
    // Parse the JSON response
    const JsonObject response = JsonObject::Parse(c_sampleSuggestionsResponse);

    std::vector<StorageProviderSuggestionResult> suggestionResults;
    for (const auto& result : response.GetNamedArray(L"results"))
    {
        const JsonObject resultObject = result.GetObject();

        StorageProviderSuggestionResult suggestionResult;
        suggestionResult.Kind(StorageProviderResultKind::Recent);
        suggestionResult.FilePath(resultObject.GetNamedString(L"filePath"));
        suggestionResult.RemoteFileId(resultObject.GetNamedString(L"id"));

        const JsonObject requestedProperties = resultObject.GetNamedObject(L"requestedProperties");
        for (const auto& propertyName : propertiesToFetch)
        {
            if (const IJsonValue value = requestedProperties.TryLookup(propertyName))
            {
                suggestionResult.RequestedProperties().Insert(propertyName, box_value(value.GetString()));
            }
        }
        suggestionResults.push_back(std::move(suggestionResult));
    }

    return suggestionResults;
}

StorageProviderQueryResultSet GetSuggestions(StorageProviderSuggestionsQueryOptions const& options)
{
    StorageProviderSearchQueryStatus status{ StorageProviderSearchQueryStatus::QueryNotSupported };

    std::vector<StorageProviderSuggestionResult> results;
    if (options.SuggestionsKind() == StorageProviderResultKind::Recent)
    {
        results = ParseSuggestionResponse(options.PropertiesToFetch());
        status = StorageProviderSearchQueryStatus::Success;
    }

    StorageProviderQueryResultSet resultSet{ com_array<IStorageProviderQueryResult>(std::move(results)) };
    resultSet.Status(status);
    return resultSet;
}

Remarks

The returned StorageProviderQueryResultSet is expected to return StorageProviderSuggestionResult objects from its GetResults method.

If the SuggestionsKind passed in the options object is not supported by the cloud provider, they should return a StorageProviderQueryResultSet object with the Status set to QueryNotSupported.

To support offline scenarios and improve reliability, the cloud storage provider should cache the results of any requests made to backing services and return cached results when appropriate.

Applies to