StorageItemAccessList StorageItemAccessList StorageItemAccessList StorageItemAccessList Class

Definition

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 : sealed class StorageItemAccessList : IStorageItemAccessList
public sealed class StorageItemAccessList : IStorageItemAccessList
Public NotInheritable Class StorageItemAccessList Implements IStorageItemAccessList
// 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 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
}
savePicker.pickSaveFileAsync().then(function (file) {
    if (file) {
        // Add to MRU with metadata (For example, a string that represents the date)
        var mruToken = StorageApplicationPermissions.mostRecentlyUsedList.add(file, "20120716");

        // Add to FA without metadata
        var 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 saving files with file picker, see How to save files through . To learn about accessing files, see Quickstart: Accessing files with .

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 How to 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 Entries Entries Entries

Gets an object for retrieving storage items from the access list.

public : AccessListEntryView Entries { get; }
public AccessListEntryView Entries { get; }
Public ReadOnly Property Entries As AccessListEntryView
var accessListEntryView = storageItemAccessList.entries;
Value
AccessListEntryView AccessListEntryView AccessListEntryView AccessListEntryView

The object for retrieving storage items.

MaximumItemsAllowed MaximumItemsAllowed MaximumItemsAllowed MaximumItemsAllowed

Gets the maximum number of storage items that the access list can contain.

public : unsigned int MaximumItemsAllowed { get; }
public uint MaximumItemsAllowed { get; }
Public ReadOnly Property MaximumItemsAllowed As uint
var uint = storageItemAccessList.maximumItemsAllowed;
Value
unsigned int uint uint uint

The maximum number of storage items.

Methods

Add(IStorageItem) Add(IStorageItem) Add(IStorageItem) Add(IStorageItem)

Adds a new storage item to the access list.

public : Platform::String Add(IStorageItem file)
public string Add(IStorageItem file)
Public Function Add(file As IStorageItem) As string
var string = storageItemAccessList.add(file);
Parameters
file
IStorageItem IStorageItem IStorageItem IStorageItem

The storage item to add.

Returns
Platform::String string string string

A token that the app can use later to retrieve the storage item.

See Also

Add(IStorageItem, String) Add(IStorageItem, String) Add(IStorageItem, String) Add(IStorageItem, String)

Adds a new storage item and accompanying metadata to the access list.

public : Platform::String Add(IStorageItem file, Platform::String metadata)
public string Add(IStorageItem file, String metadata)
Public Function Add(file As IStorageItem, metadata As String) As string
var string = storageItemAccessList.add(file, metadata);
Parameters
file
IStorageItem IStorageItem IStorageItem IStorageItem

The storage item to add.

metadata
Platform::String String String String

Optional metadata to associate with the storage item.

Returns
Platform::String string string string

A token that the app can use later to retrieve the storage item.

See Also

AddOrReplace(String, IStorageItem) AddOrReplace(String, IStorageItem) AddOrReplace(String, IStorageItem) AddOrReplace(String, IStorageItem)

Adds a new storage item to the access list, or replaces the specified item if it already exists in the list.

public : void AddOrReplace(Platform::String token, IStorageItem file)
public void AddOrReplace(String token, IStorageItem file)
Public Function AddOrReplace(token As String, file As IStorageItem) As void
storageItemAccessList.addOrReplace(token, file);
Parameters
token
Platform::String String String String

The token associated with the new storage item. If the access list already contains a storage item that has this token, the new item replaces the existing one.

file
IStorageItem IStorageItem IStorageItem IStorageItem

The storage item to add or replace.

See Also

AddOrReplace(String, IStorageItem, String) AddOrReplace(String, IStorageItem, String) AddOrReplace(String, IStorageItem, String) 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.

public : void AddOrReplace(Platform::String token, IStorageItem file, Platform::String metadata)
public void AddOrReplace(String token, IStorageItem file, String metadata)
Public Function AddOrReplace(token As String, file As IStorageItem, metadata As String) As void
storageItemAccessList.addOrReplace(token, file, metadata);
Parameters
token
Platform::String String String String

A token that the app can use later to retrieve this storage item.

file
IStorageItem IStorageItem IStorageItem IStorageItem

The storage item to add or replace.

metadata
Platform::String String String String

Optional metadata to associate with the storage item.

See Also

CheckAccess(IStorageItem) CheckAccess(IStorageItem) CheckAccess(IStorageItem) CheckAccess(IStorageItem)

Determines whether the app has access to the specified storage item in the access list.

public : Platform::Boolean CheckAccess(IStorageItem file)
public bool CheckAccess(IStorageItem file)
Public Function CheckAccess(file As IStorageItem) As bool
var bool = storageItemAccessList.checkAccess(file);
Parameters
file
IStorageItem IStorageItem IStorageItem IStorageItem

The storage item to check for access.

Returns
Platform::Boolean bool bool bool

True if the app can access the storage item; otherwise false.

Clear() Clear() Clear() Clear()

Removes all storage items from the access list.

public : void Clear()
public void Clear()
Public Function Clear() As void
storageItemAccessList.clear();

ContainsItem(String) ContainsItem(String) ContainsItem(String) ContainsItem(String)

Determines whether the access list contains the specified storage item.

public : Platform::Boolean ContainsItem(Platform::String token)
public bool ContainsItem(String token)
Public Function ContainsItem(token As String) As bool
var bool = storageItemAccessList.containsItem(token);
Parameters
token
Platform::String String String String

The token of the storage item to look for.

Returns
Platform::Boolean bool bool bool

True if the access list contains the specified storage item; false otherwise.

GetFileAsync(String) GetFileAsync(String) GetFileAsync(String) GetFileAsync(String)

Retrieves the specified StorageFile from the list.

public : IAsyncOperation<StorageFile> GetFileAsync(Platform::String token)
public IAsyncOperation<StorageFile> GetFileAsync(String token)
Public Function GetFileAsync(token As String) As IAsyncOperation( Of StorageFile )
Windows.Storage.AccessCache.StorageItemAccessList.getFileAsync(token).done( /* Your success and error handlers */ );
Parameters
token
Platform::String String String String

The token of the StorageFile to retrieve.

Returns

When this method completes successfully, it returns the StorageFile that is associated with the specified token.

See Also

GetFileAsync(String, AccessCacheOptions) GetFileAsync(String, AccessCacheOptions) GetFileAsync(String, AccessCacheOptions) GetFileAsync(String, AccessCacheOptions)

Retrieves the StorageFile from the list using the specified options.

public : IAsyncOperation<StorageFile> GetFileAsync(Platform::String token, AccessCacheOptions options)
public IAsyncOperation<StorageFile> GetFileAsync(String token, AccessCacheOptions options)
Public Function GetFileAsync(token As String, options As AccessCacheOptions) As IAsyncOperation( Of StorageFile )
Windows.Storage.AccessCache.StorageItemAccessList.getFileAsync(token, options).done( /* Your success and error handlers */ );
Parameters
token
Platform::String String String String

The token of the StorageFile to retrieve.

options
AccessCacheOptions AccessCacheOptions AccessCacheOptions AccessCacheOptions

The enum value that describes the behavior to use when the app accesses the item.

Returns

When this method completes successfully, it returns the StorageFile that is associated with the specified token.

See Also

GetFolderAsync(String) GetFolderAsync(String) GetFolderAsync(String) GetFolderAsync(String)

Retrieves the specified StorageFolder from the list.

public : IAsyncOperation<StorageFolder> GetFolderAsync(Platform::String token)
public IAsyncOperation<StorageFolder> GetFolderAsync(String token)
Public Function GetFolderAsync(token As String) As IAsyncOperation( Of StorageFolder )
Windows.Storage.AccessCache.StorageItemAccessList.getFolderAsync(token).done( /* Your success and error handlers */ );
Parameters
token
Platform::String String String String

The token of the StorageFolder to retrieve.

Returns

When this method completes successfully, it returns the StorageFolder that is associated with the specified token.

See Also

GetFolderAsync(String, AccessCacheOptions) GetFolderAsync(String, AccessCacheOptions) GetFolderAsync(String, AccessCacheOptions) GetFolderAsync(String, AccessCacheOptions)

Retrieves the specified StorageFolder from the list using the specified options.

public : IAsyncOperation<StorageFolder> GetFolderAsync(Platform::String token, AccessCacheOptions options)
public IAsyncOperation<StorageFolder> GetFolderAsync(String token, AccessCacheOptions options)
Public Function GetFolderAsync(token As String, options As AccessCacheOptions) As IAsyncOperation( Of StorageFolder )
Windows.Storage.AccessCache.StorageItemAccessList.getFolderAsync(token, options).done( /* Your success and error handlers */ );
Parameters
token
Platform::String String String String

The token of the StorageFolder to retrieve.

options
AccessCacheOptions AccessCacheOptions AccessCacheOptions AccessCacheOptions

The enum value that describes the behavior to use when the app accesses the item.

Returns

When this method completes successfully, it returns the StorageFolder that is associated with the specified token.

See Also

GetItemAsync(String) GetItemAsync(String) GetItemAsync(String) GetItemAsync(String)

Retrieves the specified item (like a file or folder) from the most recently used (MRU) list.

public : IAsyncOperation<IStorageItem> GetItemAsync(Platform::String token)
public IAsyncOperation<IStorageItem> GetItemAsync(String token)
Public Function GetItemAsync(token As String) As IAsyncOperation( Of IStorageItem )
Windows.Storage.AccessCache.StorageItemAccessList.getItemAsync(token).done( /* Your success and error handlers */ );
Parameters
token
Platform::String String String String

The token of the item to retrieve.

Returns

When this method completes successfully, it returns the item (type IStorageItem ) that is associated with the specified token.

See Also

GetItemAsync(String, AccessCacheOptions) GetItemAsync(String, AccessCacheOptions) GetItemAsync(String, AccessCacheOptions) GetItemAsync(String, AccessCacheOptions)

Retrieves the specified item (like a file or folder) from the list using the specified options.

public : IAsyncOperation<IStorageItem> GetItemAsync(Platform::String token, AccessCacheOptions options)
public IAsyncOperation<IStorageItem> GetItemAsync(String token, AccessCacheOptions options)
Public Function GetItemAsync(token As String, options As AccessCacheOptions) As IAsyncOperation( Of IStorageItem )
Windows.Storage.AccessCache.StorageItemAccessList.getItemAsync(token, options).done( /* Your success and error handlers */ );
Parameters
token
Platform::String String String String

The token of the item to retrieve.

options
AccessCacheOptions AccessCacheOptions AccessCacheOptions AccessCacheOptions

The enum value that describes the behavior to use when the app accesses the item.

Returns

When this method completes successfully, it returns the item (type IStorageItem ) that is associated with the specified token.

See Also

Remove(String) Remove(String) Remove(String) Remove(String)

Removes the specified storage item from the access list.

public : void Remove(Platform::String token)
public void Remove(String token)
Public Function Remove(token As String) As void
storageItemAccessList.remove(token);
Parameters
token
Platform::String String String String

The token of the storage item to remove.