StorageItemAccessList Class

Definition

Namespace:

Windows.Storage.AccessCache

Represents your app's future-access list (obtained from the static StorageApplicationPermissions.FutureAccessList property). By picking files and folders, your user grants your app permission to access items that might not be accessible otherwise. If you add these items to your future-access list then you'll retain that permission when your app wants to access those items again later. Items are stored in the future-access list as StorageFile and StorageFolder objects.

public ref class StorageItemAccessList sealed : IStorageItemAccessList

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
class StorageItemAccessList final : IStorageItemAccessList

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
public sealed class StorageItemAccessList : IStorageItemAccessList

Public NotInheritable Class StorageItemAccessList
Implements IStorageItemAccessList

Inheritance

Object Platform::Object IInspectable StorageItemAccessList

Attributes

ContractVersionAttribute

Implements

IStorageItemAccessList

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)

Examples

This example demonstrates how to add an item to the app's FutureAccessList and MostRecentlyUsedList.

StorageFile file = await savePicker.PickSaveFileAsync();
if (file != null)
{
    // Add to MRU with metadata (For example, a string that represents the date)
    string mruToken = Windows.Storage.AccessCache.StorageApplicationPermissions.MostRecentlyUsedList.Add(file, "20120716");

    // Add to FA without metadata
    string faToken = Windows.Storage.AccessCache.StorageApplicationPermissions.FutureAccessList.Add(file);  
}
else
{
    // The file picker was dismissed with no file selected to save
}

#include <sstream>
#include <winrt/Windows.Storage.h>
#include <winrt/Windows.Storage.AccessCache.h>
#include <winrt/Windows.Storage.Pickers.h>
using namespace winrt;
using namespace Windows::Storage::Pickers;
using namespace Windows::Storage;
...
winrt::fire_and_forget AddToLists()
{
    FileSavePicker savePicker;
    auto plainTextExtensions{ winrt::single_threaded_vector<winrt::hstring>() };
    plainTextExtensions.Append(L".txt");
    savePicker.FileTypeChoices().Insert(L"Plain Text", plainTextExtensions);
    savePicker.SuggestedFileName(L"New Document");

    StorageFile file{ co_await savePicker.PickSaveFileAsync() };
    if (file)
    {
        // Add to MRU with metadata (For example, a string that represents the date)
        winrt::hstring mruToken { Windows::Storage::AccessCache::StorageApplicationPermissions::MostRecentlyUsedList().Add(file, L"20120716") };

        // Add to FA without metadata
        winrt::hstring faToken { Windows::Storage::AccessCache::StorageApplicationPermissions::FutureAccessList().Add(file) };
    }
    else
    {
        // The file picker was dismissed with no file selected to save
    }
}

We recommend that you store the tokens that are returned by StorageApplicationPermissions.MostRecentlyUsedList.Add and StorageApplicationPermissions.FutureAccessList.Add so that you can use them to retrieve the respective list entry for the item that you added. In the example, we store the tokens in mruToken and faToken respectively but we don't do anything else with them.

Additionally, the savePicker variable in the example contains a FileSavePicker object that was created by the sample. To learn more about using the file picker, see Open files and folders with a picker and Save a file with a picker.

Remarks

Use this future-access list to preserve access to files and locations that may not be included with the accessible locations specified by the capabilities in your app manifest. For example, if your app uses a file picker to access a file (or location), we recommend that you store the StorageFile that is returned from the file picker in this future-access list.

This list can store up to 1000 items and must be maintained by the app.

To see more code examples, see the File picker sample and the File access sample.

To learn about using the FutureAccessList and MostRecentlyUsedList, see Track recently used files and folders.

To learn more about what files and locations your app has permission to access, see File access permissions.

Properties

Entries	Gets an object for retrieving storage items from the access list.
MaximumItemsAllowed	Gets the maximum number of storage items that the access list can contain.

Methods

Add(IStorageItem, String)	Adds a new storage item and accompanying metadata to the access list.
Add(IStorageItem)	Adds a new storage item to the access list.
AddOrReplace(String, IStorageItem, String)	Adds a new storage item and accompanying metadata to the access list, or replaces the specified item if it already exists in the list.
AddOrReplace(String, IStorageItem)	Adds a new storage item to the access list, or replaces the specified item if it already exists in the list.
CheckAccess(IStorageItem)	Determines whether the app has access to the specified storage item in the access list.
Clear()	Removes all storage items from the access list.
ContainsItem(String)	Determines whether the access list contains the specified storage item.
GetFileAsync(String, AccessCacheOptions)	Retrieves the StorageFile from the list using the specified options.
GetFileAsync(String)	Retrieves the specified StorageFile from the list.
GetFolderAsync(String, AccessCacheOptions)	Retrieves the specified StorageFolder from the list using the specified options.
GetFolderAsync(String)	Retrieves the specified StorageFolder from the list.
GetItemAsync(String, AccessCacheOptions)	Retrieves the specified item (like a file or folder) from the list using the specified options.
GetItemAsync(String)	Retrieves the specified item (like a file or folder) from the most recently used (MRU) list.
Remove(String)	Removes the specified storage item from the access list.

See also

• FutureAccessList