Change copyright from Intevation to BSI
[gpgme.git] / lang / qt / src / cryptoconfig.h
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 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     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 class QGPGME_EXPORT CryptoConfigGroup
267 {
268
269 public:
270     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 class QGPGME_EXPORT CryptoConfigComponent
316 {
317
318 public:
319     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 class QGPGME_EXPORT CryptoConfig
356 {
357
358 public:
359     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     CryptoConfigEntry *entry(const QString &componentName, const QString &groupName, const QString &entryName) const
383     {
384         const QGpgME::CryptoConfigComponent *comp = component(componentName);
385         const QGpgME::CryptoConfigGroup *group = comp ? comp->group(groupName) : 0;
386         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 */