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