Line data Source code
1 : /*
2 : cryptoconfig.h
3 :
4 : This file is part of qgpgme, the Qt API binding for gpgme
5 : Copyright (c) 2004 Klarälvdalens Datakonsult AB
6 : Copyright (c) 2016 by Bundesamt für Sicherheit in der Informationstechnik
7 : Software engineering by Intevation GmbH
8 :
9 : QGpgME is free software; you can redistribute it and/or
10 : modify it under the terms of the GNU General Public License as
11 : published by the Free Software Foundation; either version 2 of the
12 : License, or (at your option) any later version.
13 :
14 : QGpgME is distributed in the hope that it will be useful,
15 : but WITHOUT ANY WARRANTY; without even the implied warranty of
16 : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 : General Public License for more details.
18 :
19 : You should have received a copy of the GNU General Public License
20 : along with this program; if not, write to the Free Software
21 : Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22 :
23 : In addition, as a special exception, the copyright holders give
24 : permission to link the code of this program with any edition of
25 : the Qt library by Trolltech AS, Norway (or with modified versions
26 : of Qt that use the same license as Qt), and distribute linked
27 : combinations including the two. You must obey the GNU General
28 : Public License in all respects for all of the code used other than
29 : Qt. If you modify this file, you may extend this exception to
30 : your version of the file, but you are not obligated to do so. If
31 : you do not wish to do so, delete this exception statement from
32 : your version.
33 : */
34 :
35 : #ifndef CRYPTOCONFIG_H
36 : #define CRYPTOCONFIG_H
37 :
38 : #include "qgpgme_export.h"
39 : #ifdef __cplusplus
40 : /* we read this file from a C compiler, and are only interested in the
41 : * enums... */
42 :
43 : #include <QUrl>
44 :
45 : #include <vector>
46 :
47 : /* Start reading this file from the bottom up :) */
48 :
49 : namespace QGpgME
50 : {
51 :
52 : /**
53 : * Description of a single option
54 : */
55 2323 : class QGPGME_EXPORT CryptoConfigEntry
56 : {
57 :
58 : public:
59 : #endif /* __cplusplus */
60 : /**
61 : @li basic This option should always be offered to the user.
62 : @li advanced This option may be offered to advanced users.
63 : @li expert This option should only be offered to expert users.
64 : */
65 : enum Level { Level_Basic = 0,
66 : Level_Advanced = 1,
67 : Level_Expert = 2
68 : };
69 :
70 : /**
71 : Type of the argument
72 : @li ArgType_None The option is set or not set, but no argument.
73 : @li ArgType_String An unformatted string.
74 : @li ArgType_Int A signed integer number.
75 : @li ArgType_UInt An unsigned integer number.
76 : @li ArgType_Path A string that describes the pathname of a file.
77 : The file does not necessarily need to exist.
78 : Separated from string so that e.g. a FileDialog can be used.
79 : @li ArgType_DirPath A string that describes the pathname of a directory.
80 : The directory does not necessarily need to exist.
81 : Separated from path so that e.g. a FileDialog can be used which only
82 : allows directories to be selected.
83 : @li ArgType_LDAPURL A LDAP URL
84 : Separated from URL so that a more specific widget can be shown, hiding the url syntax
85 : */
86 : enum ArgType { ArgType_None = 0,
87 : ArgType_String = 1,
88 : ArgType_Int = 2,
89 : ArgType_UInt = 3,
90 : ArgType_Path = 4,
91 : /* Nr. 5 was URL historically. */
92 : ArgType_LDAPURL = 6,
93 : ArgType_DirPath = 7,
94 :
95 : NumArgType
96 : };
97 :
98 : #ifdef __cplusplus
99 2222 : virtual ~CryptoConfigEntry() {}
100 :
101 : /**
102 : * Return the internal name of this entry
103 : */
104 : virtual QString name() const = 0;
105 :
106 : /**
107 : * @return user-visible description of this entry
108 : */
109 : virtual QString description() const = 0;
110 :
111 : /**
112 : * @return "component/group/name"
113 : */
114 : virtual QString path() const = 0;
115 :
116 : /**
117 : * @return true if the argument is optional
118 : */
119 : virtual bool isOptional() const = 0;
120 :
121 : /**
122 : * @return true if the entry is readonly
123 : */
124 : virtual bool isReadOnly() const = 0;
125 :
126 : /**
127 : * @return true if the argument can be given multiple times
128 : */
129 : virtual bool isList() const = 0;
130 :
131 : /**
132 : * @return true if the argument can be changed at runtime
133 : */
134 : virtual bool isRuntime() const = 0;
135 :
136 : /**
137 : * User level
138 : */
139 : virtual Level level() const = 0;
140 :
141 : /**
142 : * Argument type
143 : */
144 : virtual ArgType argType() const = 0;
145 :
146 : /**
147 : * Return true if the option is set, i.e. different from default
148 : */
149 : virtual bool isSet() const = 0;
150 :
151 : /**
152 : * Return value as a bool (only allowed for ArgType_None)
153 : */
154 : virtual bool boolValue() const = 0;
155 :
156 : /**
157 : * Return value as a string (available for all argtypes)
158 : * The returned string can be empty (explicitly set to empty) or null (not set).
159 : */
160 : virtual QString stringValue() const = 0;
161 :
162 : /**
163 : * Return value as a signed int
164 : */
165 : virtual int intValue() const = 0;
166 :
167 : /**
168 : * Return value as an unsigned int
169 : */
170 : virtual unsigned int uintValue() const = 0;
171 :
172 : /**
173 : * Return value as a URL (only meaningful for Path and URL argtypes)
174 : */
175 : virtual QUrl urlValue() const = 0;
176 :
177 : /**
178 : * Return number of times the option is set (only valid for ArgType_None, if isList())
179 : */
180 : virtual unsigned int numberOfTimesSet() const = 0;
181 :
182 : /**
183 : * Return value as a list of signed ints
184 : */
185 : virtual std::vector<int> intValueList() const = 0;
186 :
187 : /**
188 : * Return value as a list of unsigned ints
189 : */
190 : virtual std::vector<unsigned int> uintValueList() const = 0;
191 :
192 : /**
193 : * Return value as a list of URLs (only meaningful for Path and URL argtypes, if isList())
194 : */
195 : virtual QList<QUrl> urlValueList() const = 0;
196 :
197 : /**
198 : * Reset an option to its default value
199 : */
200 : virtual void resetToDefault() = 0;
201 :
202 : /**
203 : * Define whether the option is set or not (only allowed for ArgType_None)
204 : * #### TODO: and for options with optional args
205 : */
206 : virtual void setBoolValue(bool) = 0;
207 :
208 : /**
209 : * Set string value (allowed for all argtypes)
210 : */
211 : virtual void setStringValue(const QString &) = 0;
212 :
213 : /**
214 : * Set a new signed int value
215 : */
216 : virtual void setIntValue(int) = 0;
217 :
218 : /**
219 : * Set a new unsigned int value
220 : */
221 : virtual void setUIntValue(unsigned int) = 0;
222 :
223 : /**
224 : * Set value as a URL (only meaningful for Path (if local) and URL argtypes)
225 : */
226 : virtual void setURLValue(const QUrl &) = 0;
227 :
228 : /**
229 : * Set the number of times the option is set (only valid for ArgType_None, if isList())
230 : */
231 : virtual void setNumberOfTimesSet(unsigned int) = 0;
232 :
233 : /**
234 : * Set a new list of signed int values
235 : */
236 : virtual void setIntValueList(const std::vector<int> &) = 0;
237 :
238 : /**
239 : * Set a new list of unsigned int values
240 : */
241 : virtual void setUIntValueList(const std::vector<unsigned int> &) = 0;
242 :
243 : /**
244 : * Set value as a URL list (only meaningful for Path (if all URLs are local) and URL argtypes, if isList())
245 : */
246 : virtual void setURLValueList(const QList<QUrl> &) = 0;
247 :
248 : /**
249 : * @return true if the value was changed
250 : */
251 : virtual bool isDirty() const = 0;
252 :
253 : // Design change from here on we are closely bound to one implementation
254 : // of cryptoconfig. To avoid ABI breaks with every new function we
255 : // add real functions from now on.
256 :
257 : /**
258 : * @return a stringValueList.
259 : */
260 : QStringList stringValueList() const;
261 : };
262 :
263 : /**
264 : * Group containing a set of config options
265 : */
266 621 : class QGPGME_EXPORT CryptoConfigGroup
267 : {
268 :
269 : public:
270 594 : virtual ~CryptoConfigGroup() {}
271 :
272 : /**
273 : * Return the internal name of this group
274 : */
275 : virtual QString name() const = 0;
276 :
277 : /**
278 : * Return the name of the icon for this group
279 : */
280 : virtual QString iconName() const = 0;
281 :
282 : /**
283 : * @return user-visible description of this group
284 : */
285 : virtual QString description() const = 0;
286 :
287 : /**
288 : * @return "component/group"
289 : */
290 : virtual QString path() const = 0;
291 :
292 : /**
293 : * User level
294 : */
295 : virtual CryptoConfigEntry::Level level() const = 0;
296 :
297 : /**
298 : * Returns the list of entries that are known by this group.
299 : *
300 : * @return list of group entry names.
301 : **/
302 : virtual QStringList entryList() const = 0;
303 :
304 : /**
305 : * @return the configuration object for a given entry in this group
306 : * The object is owned by CryptoConfigGroup, don't delete it.
307 : * Groups cannot be nested, so all entries returned here are pure entries, no groups.
308 : */
309 : virtual CryptoConfigEntry *entry(const QString &name) const = 0;
310 : };
311 :
312 : /**
313 : * Crypto config for one component (e.g. gpg-agent, dirmngr etc.)
314 : */
315 138 : class QGPGME_EXPORT CryptoConfigComponent
316 : {
317 :
318 : public:
319 132 : virtual ~CryptoConfigComponent() {}
320 :
321 : /**
322 : * Return the internal name of this component
323 : */
324 : virtual QString name() const = 0;
325 :
326 : /**
327 : * Return the name of the icon for this component
328 : */
329 : virtual QString iconName() const = 0;
330 :
331 : /**
332 : * Return user-visible description of this component
333 : */
334 : virtual QString description() const = 0;
335 :
336 : /**
337 : * Returns the list of groups that are known about.
338 : *
339 : * @return list of group names. One of them can be "<nogroup>", which is the group where all
340 : * "toplevel" options (belonging to no group) are.
341 : */
342 : virtual QStringList groupList() const = 0;
343 :
344 : /**
345 : * @return the configuration object for a given group
346 : * The object is owned by CryptoConfigComponent, don't delete it.
347 : */
348 : virtual CryptoConfigGroup *group(const QString &name) const = 0;
349 :
350 : };
351 :
352 : /**
353 : * Main interface to crypto configuration.
354 : */
355 1 : class QGPGME_EXPORT CryptoConfig
356 : {
357 :
358 : public:
359 0 : virtual ~CryptoConfig() {}
360 :
361 : /**
362 : * Returns the list of known components (e.g. "gpg-agent", "dirmngr" etc.).
363 : * Use @ref component() to retrieve more information about each one.
364 : * @return list of component names.
365 : **/
366 : virtual QStringList componentList() const = 0;
367 :
368 : /**
369 : * @return the configuration object for a given component
370 : * The object is owned by CryptoConfig, don't delete it.
371 : */
372 : virtual CryptoConfigComponent *component(const QString &name) const = 0;
373 :
374 : /**
375 : * Convenience method to get hold of a single configuration entry when
376 : * its component, group and name are known. This can be used to read
377 : * the value and/or to set a value to it.
378 : *
379 : * @return the configuration object for a single configuration entry, 0 if not found.
380 : * The object is owned by CryptoConfig, don't delete it.
381 : */
382 33 : CryptoConfigEntry *entry(const QString &componentName, const QString &groupName, const QString &entryName) const
383 : {
384 33 : const QGpgME::CryptoConfigComponent *comp = component(componentName);
385 33 : const QGpgME::CryptoConfigGroup *group = comp ? comp->group(groupName) : 0;
386 33 : return group ? group->entry(entryName) : 0;
387 : }
388 :
389 : /**
390 : * Write back changes
391 : *
392 : * @param runtime this parameter is ignored. Changes will always
393 : * be made with --runtime set.
394 : */
395 : virtual void sync(bool runtime) = 0;
396 :
397 : /**
398 : * Tells the CryptoConfig to discard any cached information, including
399 : * all components, groups and entries.
400 : * Call this to free some memory when you won't be using the object
401 : * for some time.
402 : * DON'T call this if you're holding pointers to components, groups or entries.
403 : */
404 : virtual void clear() = 0;
405 : };
406 :
407 : }
408 : #endif /* __cplusplus */
409 : #endif /* CRYPTOCONFIG_H */
|
