WindowsAppSDK/dev/ApplicationData/ApplicationData.idl at 5eeeaf6e4299cfaac5f58395fdb63c3360092a33 · microsoft/WindowsAppSDK · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
// Copyright (c) Microsoft Corporation and Contributors.
// Licensed under the MIT License.

#include <TerminalVelocityFeatures-ApplicationData.h>

namespace Microsoft.Windows.Storage
{
    [contractversion(2)]
    apicontract ApplicationDataContract{};

    /// Specifies the type of data store.
    /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdatalocality
    [contract(ApplicationDataContract, 1)]
    enum ApplicationDataLocality
    {
        // NOTE: Values 0-99 match Windows.Storage.ApplicationDataLocality.
        //       Values 1000+ are unique to us here.
        Local = 0,
        LocalCache = 3,
        SharedLocal = 4,
        Temporary = 2,
        Machine = 1000,
    };

    /// Specifies options for creating application data containers or returning existing containers.
    [contract(ApplicationDataContract, 1)]
    enum ApplicationDataCreateDisposition
    {
        /// Always returns the specified container. Creates the container if it does not exist.
        Always = 0,

        // Returns the specified container only if it already exists. Raises an exception of type System.Exception if the specified container does not exist.
        Existing,
    };

    /// Represents a container for settings. The methods and properties of this class support creating, deleting, enumerating, and traversing the container hierarchy.
    /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdatacontainer
    [contract(ApplicationDataContract, 1)]
    runtimeclass ApplicationDataContainer : Windows.Foundation.IClosable
    {
        /// Return the child settings containers of the settings container.
        /// https://learn.microsoft.com/uwp/api/windows.storage.applicationdatacontainer.containers
        IMap<String, ApplicationDataContainer> Containers { get; };

        /// Return the name of the current settings container.
        /// https://learn.microsoft.com/uwp/api/windows.storage.applicationdatacontainer.name
        String Name { get; };

        /// Return the type of the app data store that is associated with the settings container.
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdatacontainer.locality
        ApplicationDataLocality Locality { get; };

        /// Return an object that represents the settings in the settings container.
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdatacontainer.values
        Windows.Foundation.Collections.IPropertySet Values { get; };

        /// Create or open the specified settings container in the settings container.
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdatacontainer.createcontainer
        ApplicationDataContainer CreateContainer(String name, ApplicationDataCreateDisposition disposition);

        /// Delete the specified settings container, its subcontainers, and all settings in the hierarchy.
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdatacontainer.deletecontainer
        void DeleteContainer(String name);
    };

    /// Provides access to the application data store.
    /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata
    [contract(ApplicationDataContract, 1)]
    runtimeclass ApplicationData : Windows.Foundation.IClosable
    {
        /// Get an instance of ApplicationData for the current user.
        /// @note Requires the current process has package identity.
        /// @note This is equivalent to Windows.Storage.ApplicationData.Current if running in an AppContainer.
        /// @note This is equivalent to Windows.Storage.ApplicationDataManager.CreateForPackageFamily(GetCurrentPackageFamilyName()) if not running in an AppContainer.
        static ApplicationData GetDefault();

        /// Get an instance of ApplicationData for the specified user.
        /// @note This is equivalent to Windows.Storage.ApplicationData.GetForUserAsync()
        /// @note GetForUserAsync(null) is equivalent to GetDefault()
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.getforuserasync
        static ApplicationData GetForUser(Windows.System.User user);

        /// Get an instance of ApplicationData for the specified package family for the current user.
        /// @note This is equivalent to Windows.Storage.ApplicationDataManager.CreateForPackageFamily()
        /// @see https://learn.microsoft.com/uwp/api/windows.management.core.applicationdatamanager.createforpackagefamily
        static ApplicationData GetForPackageFamily(String packageFamilyName);

        /// Get an instance of ApplicationData for the specified unpackaged app for the current user.
        /// @note This method respects impersonation.
        /// @warning The returned instance of ApplicationData does not support LocalCache, PublisherCache or SharedLocal features.
        [contract(ApplicationDataContract, 2)]
        static ApplicationData GetForUnpackaged(String publisher, String product);

        /// Return true if the package family supports the machine data store.
        Boolean IsMachinePathSupported { get; };

        /// Return the path for the local cache data store not included in backup and restore operations.
        /// @note This is equivalent to Windows.Storage.ApplicationData.LocalCacheFolder().Path()
        /// @warning This method is not supported if the ApplicationData instance was acquired via GetForUnpackaged().
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.localcachefolder
        String LocalCachePath { get; };

        /// Return the path for the local data store. This location is backed up to the cloud.
        /// @note This is equivalent to Windows.Storage.ApplicationData.LocalFolder().Path()
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.localfolder
        String LocalPath { get; };

        /// Return the path for the machine data store.
        /// @note This location is per-machine (not per-user like other *Path properties).
        /// @note Empty string is returned if not supported.
        /// @see IsMachinePathSupported
        String MachinePath { get; };

        /// Return the path for the shared data store.
        /// @note This is equivalent to Windows.Storage.ApplicationData.SharedLocalFolder().Path()
        /// @warning This method is not supported if the ApplicationData instance was acquired via GetForUnpackaged().
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.sharedlocalfolder
        String SharedLocalPath { get; };

        /// Return the path for the temporary data store.
        /// @note This is equivalent to Windows.Storage.ApplicationData.TemporaryFolder().Path()
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.temporaryfolder
        String TemporaryPath { get; };

        /// Return a StorageFolder for the local cache data store not included in backup and restore operations.
        /// @warning This method is not supported if the ApplicationData instance was acquired via GetForUnpackaged().
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.localcachefolder
        Windows.Storage.StorageFolder LocalCacheFolder { get; };

        /// Return a StorageFolder for the local data store. This location is backed up to the cloud.
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.localfolder
        Windows.Storage.StorageFolder LocalFolder { get; };

        /// Return a StorageFolder for the machine data store.
        /// @note This location is per-machine (not per-user like other *Folder properties).
        /// @note `null` is returned if not supported.
        /// @see IsMachinePathSupported
        Windows.Storage.StorageFolder MachineFolder { get; };

        /// Return a StorageFolder for the shared data store.
        /// @warning This method is not supported if the ApplicationData instance was acquired via GetForUnpackaged().
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.sharedlocalfolder
        Windows.Storage.StorageFolder SharedLocalFolder { get; };

        /// Return a StorageFolder for the temporary data store.
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.temporaryfolder
        Windows.Storage.StorageFolder TemporaryFolder { get; };

        /// Return the settings container in the local data store.
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.localsettings
        ApplicationDataContainer LocalSettings { get; };

        /// Remove all data from the specified data store.
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.clearasync
        Windows.Foundation.IAsyncAction ClearAsync(ApplicationDataLocality locality);

        /// Clear the files and subfolders from the specified subfolder of the shared storage folder for the publisher.
        /// @see GetPublisherCachePath()
        /// @see GetPublisherCacheFolder()
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.clearpublishercachefolderasync
        Windows.Foundation.IAsyncAction ClearPublisherCacheFolderAsync(String folderName);

        /// Return the specified path of the shared data store for the publisher of the app.
        /// @note This is equivalent to Windows.Storage.ApplicationData.GetPublisherCacheFolder(folderName).Path()
        /// @warning This method is not supported if the ApplicationData instance was acquired via GetForUnpackaged().
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.getpublishercachefolder
        String GetPublisherCachePath(String folderName);

        /// Return the specified subfolder of the shared data store for the publisher of the app.
        /// @warning This method is not supported if the ApplicationData instance was acquired via GetForUnpackaged().
        /// @see https://learn.microsoft.com/uwp/api/windows.storage.applicationdata.getpublishercachefolder
        Windows.Storage.StorageFolder GetPublisherCacheFolder(String folderName);
    }
}