Debian Codegraph @

liblomiri-app-launch/appid.h

raw
1 /*
2 * Copyright © 2016-2017 Canonical Ltd.
3 *
4 * This program is free software: you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 3, as published
6 * by the Free Software Foundation.
7 *
8 * This program is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranties of
10 * MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
11 * PURPOSE. See the GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program. If not, see <http://www.gnu.org/licenses/>.
15 *
16 * Authors:
17 * Ted Gould <[email protected]>
18 */
19
20 #include <memory>
21 #include <string>
22
23 #include "type-tagger.h"
24
25 #pragma once
26 #pragma GCC visibility push(default)
27
28 namespace lomiri
29 {
30 namespace app_launch
31 {
32
33 class Registry;
34
35 /** \brief The set of information that is used to uniquely identify an
36 application in Lomiri.
37
38 Application ID's are derived from the packaging system and the applications
39 that are defined to work in it. It resolves down to a specific version of
40 the package to resolve problems with upgrades and reduce race conditions that
41 come from installing and removing them while trying to launch them. While
42 it always resolves down to a specific version, there are functions avilable
43 here that search in various ways for the current version so higher level apps
44 can save just the package and application strings and discover the version
45 when it is required.
46 */
47 struct AppID
48 {
49 /** \private */
50 struct PackageTag;
51 /** \private */
52 struct AppNameTag;
53 /** \private */
54 struct VersionTag;
55
56 /** \private */
57 typedef TypeTagger<PackageTag, std::string> Package;
58 /** \private */
59 typedef TypeTagger<AppNameTag, std::string> AppName;
60 /** \private */
61 typedef TypeTagger<VersionTag, std::string> Version;
62
63 /** The package name of the application. Typically this is in the form of
64 $app.$developer so it could be my-app.my-name, though other formats do
65 exist and are used in the wild.
66
67 In the case of legacy applications this will be the empty string. */
68 Package package;
69 /** The string that uniquely identifies the application. This comes from
70 the package manifest. In a Click package this is the string that exists
71 under the "hooks" key in the JSON manifest. */
72 AppName appname;
73 /** Version of the package that is installed. This is always resolved when
74 creating the struct.
75
76 \note For snaps this is actually the 'revision' instead of the version
77 since that is unique where 'version' is not. */
78 Version version;
79
80 /** Turn the structure into a string. This is required for many older C based
81 interfaces that work with AppID's, but is generally not recommended for
82 anyting other than debug messages. */
83 operator std::string() const;
84
85 /** Turn the structure into a string suitable for use in DBus paths.
86 Turn this back into an AppID with parseDBusID(). This is otherwise not
87 a valid AppID string. */
88 std::string dbusID() const;
89
90 /** Turn the structure into a string without any revision information.
91 This is suitable for writing the AppID to disk. Turn this back into
92 an AppID with find(). This is otherwise not a valid AppID string. */
93 std::string persistentID() const;
94
95 /** Empty constructor for an AppID. Makes coding with them easier, but generally
96 there is nothing useful about an empty AppID. */
97 AppID();
98 /** Checks to see if an AppID is empty. */
99 bool empty() const;
100
101 /** Constructor for an AppID if all the information is known about the package.
102 Provides a precise and fast way to create an AppID if all the information
103 is already known.
104
105 \param package Name of the package
106 \param appname Name of the application
107 \param version Version of the package
108 */
109 AppID(Package pkg, AppName app, Version ver);
110
111 /** Parse a string from DBus and turn it into an AppID. This assumes that
112 the string was originally produced by dbusID(), the result is otherwise
113 undefined.
114
115 \param dbusid String from a DBus path
116 */
117 static AppID parseDBusID(const std::string& dbusid);
118 /** Parse a string and turn it into an AppID. This assumes that the string is
119 in the form: $(package)_$(app)_$(version) and will return an empty AppID
120 if not.
121
122 \param appid String with the concatenated AppID
123 */
124 static AppID parse(const std::string& appid);
125 /** Find is a more tollerant version of parse(), it handles legacy applications,
126 persistent IDs and other forms of that are in common usage.
127 It can be used, but is slower than parse() if you've got well formed data
128 already.
129
130 \note This will use the default registry instance, it is generally
131 recommended to have your own instead of using the default.
132
133 \param sappid String with the concatenated AppID
134 */
135 static AppID find(const std::string& sappid);
136 /** Find is a more tollerant version of parse(), it handles legacy applications,
137 persistent IDs and other forms of that are in common usage.
138 It can be used, but is slower than parse() if you've got well formed data
139 already.
140
141 \param registry Registry instance to use for persistant connections
142 \param sappid String with the concatenated AppID
143 */
144 static AppID find(const std::shared_ptr<Registry>& registry, const std::string& sappid);
145 /** Check to see whether a string is a valid AppID string
146
147 \param sappid String with the concatenated AppID
148 */
149 static bool valid(const std::string& sappid);
150
151 /** Control how the application list of a package is searched in the discover()
152 functions. */
153 enum class ApplicationWildcard
154 {
155 FIRST_LISTED, /**< First application listed in the manifest */
156 LAST_LISTED, /**< Last application listed in the manifest */
157 ONLY_LISTED /**< Only application listed in the manifest */
158 };
159 /** Control how the versions are searched in the discover() set of functions */
160 enum class VersionWildcard
161 {
162 CURRENT_USER_VERSION /**< The current installed version */
163 };
164
165 /** Find the AppID for an application where you only know the package
166 name.
167
168 \note This will use the default registry instance, it is generally
169 recommended to have your own instead of using the default.
170
171 \param package Name of the package
172 \param appwildcard Specification of how to search the manifest for apps
173 \param versionwildcard Specification of how to search for the version
174 */
175 static AppID discover(const std::string& package,
176 ApplicationWildcard appwildcard = ApplicationWildcard::FIRST_LISTED,
177 VersionWildcard versionwildcard = VersionWildcard::CURRENT_USER_VERSION);
178 /** Find the AppID for an application where you know the package
179 name and application name.
180
181 \note This will use the default registry instance, it is generally
182 recommended to have your own instead of using the default.
183
184 \param package Name of the package
185 \param appname Name of the application
186 \param versionwildcard Specification of how to search for the version
187 */
188 static AppID discover(const std::string& package,
189 const std::string& appname,
190 VersionWildcard versionwildcard = VersionWildcard::CURRENT_USER_VERSION);
191 /** Create an AppID providing known strings of packages and names
192
193 \note This will use the default registry instance, it is generally
194 recommended to have your own instead of using the default.
195
196 \param package Name of the package
197 \param appname Name of the application
198 \param version Version of the package
199 */
200 static AppID discover(const std::string& package, const std::string& appname, const std::string& version);
201
202 /** Find the AppID for an application where you only know the package
203 name.
204
205 \param registry Registry instance to use for persistant connections
206 \param package Name of the package
207 \param appwildcard Specification of how to search the manifest for apps
208 \param versionwildcard Specification of how to search for the version
209 */
210 static AppID discover(const std::shared_ptr<Registry>& registry,
211 const std::string& package,
212 ApplicationWildcard appwildcard = ApplicationWildcard::FIRST_LISTED,
213 VersionWildcard versionwildcard = VersionWildcard::CURRENT_USER_VERSION);
214 /** Find the AppID for an application where you know the package
215 name and application name.
216
217 \param registry Registry instance to use for persistant connections
218 \param package Name of the package
219 \param appname Name of the application
220 \param versionwildcard Specification of how to search for the version
221 */
222 static AppID discover(const std::shared_ptr<Registry>& registry,
223 const std::string& package,
224 const std::string& appname,
225 VersionWildcard versionwildcard = VersionWildcard::CURRENT_USER_VERSION);
226 /** Create an AppID providing known strings of packages and names
227
228 \param registry Registry instance to use for persistant connections
229 \param package Name of the package
230 \param appname Name of the application
231 \param version Version of the package
232 */
233 static AppID discover(const std::shared_ptr<Registry>& registry,
234 const std::string& package,
235 const std::string& appname,
236 const std::string& version);
237 };
238
239 bool operator==(const AppID& a, const AppID& b);
240 bool operator!=(const AppID& a, const AppID& b);
241 bool operator<(const AppID& a, const AppID& b);
242
243 } // namespace app_launch
244 } // namespace lomiri
245
246 #pragma GCC visibility pop