Qt: Ensure all public classes are exported
[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     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 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     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 class QGPGME_EXPORT CryptoConfigGroup
257 {
258
259 public:
260     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 class QGPGME_EXPORT CryptoConfigComponent
306 {
307
308 public:
309     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 class QGPGME_EXPORT CryptoConfig
346 {
347
348 public:
349     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 */