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