StorageItemAccessList StorageItemAccessList StorageItemAccessList StorageItemAccessList Class

Represents your app's future-access list (obtained from the static 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.

Syntax

Declaration

public sealed class StorageItemAccessListpublic sealed class StorageItemAccessListPublic NotInheritable Class StorageItemAccessList

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.

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 Add(Windows.Storage.IStorageItem) and Add(Windows.Storage.IStorageItem) 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 .

Properties summary

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

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

Methods summary

Adds a new storage item to the access list.

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

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

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

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

Removes all storage items from the access list.

Determines whether the access list contains the specified storage item.

Retrieves the specified StorageFile from the list.

Retrieves the StorageFile from the list using the specified options.

Retrieves the specified StorageFolder from the list.

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

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

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

Removes the specified storage item from the access list.

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

    Property Value

  • MaximumItemsAllowed
    MaximumItemsAllowed
    MaximumItemsAllowed
    MaximumItemsAllowed

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

    public uint MaximumItemsAllowed { get; }public uint MaximumItemsAllowed { get; }Public ReadOnly Property MaximumItemsAllowed As uint

    Property Value

    • uint
      uint
      uint
      uint

      The maximum number of storage items.

Methods

  • Add(Windows.Storage.IStorageItem)
    Add(Windows.Storage.IStorageItem)
    Add(Windows.Storage.IStorageItem)
    Add(Windows.Storage.IStorageItem)

    Adds a new storage item to the access list.

    public string Add(Windows.Storage.IStorageItem)public string Add(Windows.Storage.IStorageItem)Public Function Add(Windows.Storage.IStorageItem) As string

    Parameters

    Returns

    • string
      string
      string
      string

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

  • Add(Windows.Storage.IStorageItem,System.String)
    Add(Windows.Storage.IStorageItem,System.String)
    Add(Windows.Storage.IStorageItem,System.String)
    Add(Windows.Storage.IStorageItem,System.String)

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

    public string Add(Windows.Storage.IStorageItem,System.String)public string Add(Windows.Storage.IStorageItem,System.String)Public Function Add(Windows.Storage.IStorageItem,System.String) As string

    Parameters

    Returns

    • string
      string
      string
      string

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

  • AddOrReplace(System.String,Windows.Storage.IStorageItem)
    AddOrReplace(System.String,Windows.Storage.IStorageItem)
    AddOrReplace(System.String,Windows.Storage.IStorageItem)
    AddOrReplace(System.String,Windows.Storage.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(System.String,Windows.Storage.IStorageItem)public void AddOrReplace(System.String,Windows.Storage.IStorageItem)Public Function AddOrReplace(System.String,Windows.Storage.IStorageItem) As void

    Parameters

    • token
      System.String
      System.String
      System.String
      System.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

      The storage item to add or replace.

  • AddOrReplace(System.String,Windows.Storage.IStorageItem,System.String)
    AddOrReplace(System.String,Windows.Storage.IStorageItem,System.String)
    AddOrReplace(System.String,Windows.Storage.IStorageItem,System.String)
    AddOrReplace(System.String,Windows.Storage.IStorageItem,System.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(System.String,Windows.Storage.IStorageItem,System.String)public void AddOrReplace(System.String,Windows.Storage.IStorageItem,System.String)Public Function AddOrReplace(System.String,Windows.Storage.IStorageItem,System.String) As void

    Parameters

    • token
      System.String
      System.String
      System.String
      System.String

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

    • file

      The storage item to add or replace.

    • metadata
      System.String
      System.String
      System.String
      System.String

      Optional metadata to associate with the storage item.

  • CheckAccess(Windows.Storage.IStorageItem)
    CheckAccess(Windows.Storage.IStorageItem)
    CheckAccess(Windows.Storage.IStorageItem)
    CheckAccess(Windows.Storage.IStorageItem)

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

    public bool CheckAccess(Windows.Storage.IStorageItem)public bool CheckAccess(Windows.Storage.IStorageItem)Public Function CheckAccess(Windows.Storage.IStorageItem) As bool

    Parameters

    Returns

    • bool
      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
  • ContainsItem(System.String)
    ContainsItem(System.String)
    ContainsItem(System.String)
    ContainsItem(System.String)

    Determines whether the access list contains the specified storage item.

    public bool ContainsItem(System.String)public bool ContainsItem(System.String)Public Function ContainsItem(System.String) As bool

    Parameters

    • token
      System.String
      System.String
      System.String
      System.String

      The token of the storage item to look for.

    Returns

    • bool
      bool
      bool
      bool

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

  • GetFileAsync(System.String)
    GetFileAsync(System.String)
    GetFileAsync(System.String)
    GetFileAsync(System.String)

    Retrieves the specified StorageFile from the list.

    public IAsyncOperation<StorageFile> GetFileAsync(System.String)public IAsyncOperation<StorageFile> GetFileAsync(System.String)Public Function GetFileAsync(System.String) As IAsyncOperation( Of StorageFile )

    Parameters

    • token
      System.String
      System.String
      System.String
      System.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.

  • GetFileAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetFileAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetFileAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetFileAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)

    Retrieves the StorageFile from the list using the specified options.

    public IAsyncOperation<StorageFile> GetFileAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)public IAsyncOperation<StorageFile> GetFileAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)Public Function GetFileAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions) As IAsyncOperation( Of StorageFile )

    Parameters

    Returns

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

  • GetFolderAsync(System.String)
    GetFolderAsync(System.String)
    GetFolderAsync(System.String)
    GetFolderAsync(System.String)

    Retrieves the specified StorageFolder from the list.

    public IAsyncOperation<StorageFolder> GetFolderAsync(System.String)public IAsyncOperation<StorageFolder> GetFolderAsync(System.String)Public Function GetFolderAsync(System.String) As IAsyncOperation( Of StorageFolder )

    Parameters

    • token
      System.String
      System.String
      System.String
      System.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.

  • GetFolderAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetFolderAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetFolderAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetFolderAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)

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

    public IAsyncOperation<StorageFolder> GetFolderAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)public IAsyncOperation<StorageFolder> GetFolderAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)Public Function GetFolderAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions) As IAsyncOperation( Of StorageFolder )

    Parameters

    Returns

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

  • GetItemAsync(System.String)
    GetItemAsync(System.String)
    GetItemAsync(System.String)
    GetItemAsync(System.String)

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

    public IAsyncOperation<IStorageItem> GetItemAsync(System.String)public IAsyncOperation<IStorageItem> GetItemAsync(System.String)Public Function GetItemAsync(System.String) As IAsyncOperation( Of IStorageItem )

    Parameters

    • token
      System.String
      System.String
      System.String
      System.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.

  • GetItemAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetItemAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetItemAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)
    GetItemAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)

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

    public IAsyncOperation<IStorageItem> GetItemAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)public IAsyncOperation<IStorageItem> GetItemAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions)Public Function GetItemAsync(System.String,Windows.Storage.AccessCache.AccessCacheOptions) As IAsyncOperation( Of IStorageItem )

    Parameters

    Returns

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

  • Remove(System.String)
    Remove(System.String)
    Remove(System.String)
    Remove(System.String)

    Removes the specified storage item from the access list.

    public void Remove(System.String)public void Remove(System.String)Public Function Remove(System.String) As void

    Parameters

    • token
      System.String
      System.String
      System.String
      System.String

      The token of the storage item to remove.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.Storage.AccessCache.dll