Spelling fixes for comments and doc
[gpgme.git] / lang / cpp / README
1 GpgMEpp - C++ bindings/wrapper for GPGME
2 ----------------------------------------
3 Based on KF5gpgmepp
4
5 Overview
6 --------
7
8 GpgMEpp is a C++ wrapper (or C++ bindings) for the GnuPG project's
9 gpgme (GnuPG Made Easy) library, version 0.4.4 and later.
10
11 It is fairly complete, with some minor things still missing (in
12 particular, the key edit interface).
13
14 The design principles of this library are as follows:
15
16 1. A value-based interface (most clases are implicitly shared)
17 2. Callbacks are replaced by C++ interfaces (classes with only
18    abstract methods).
19 3. No exceptions are thrown
20 4. There is (as yet) no explicit support for multi-threaded use
21    (other than what gpgme itself provides; most notably the
22    refcounting for implicit sharing is not thread-safe)
23 5. To avoid binary incompatible interface changes, we make
24    extensive use of the d-pointer pattern and avoid virtual
25    methods; any polymorphism present is already provided by gpgme
26    itself, anyway (see e.g. Data). A notable exception of the
27    no-virtuals rule is the use of abstract classes to cover
28    C-callbacks.
29 6. Use of STL containers for improved memory management and
30    dealing with lists.
31 7. Complete abstraction of the C-API so "gpgme.h" should not
32    be needed in your project using GpgME++.
33 8. Abstraction of GnuPG's edit-key interface by prepared
34    Editinteractor classes.
35
36 GpgMEpp was originally developed as part of the KDEPIM community.
37
38 Usage
39 -----
40
41 The usage pattern of GpgMEpp closely follows GPGMEs core usage
42 pattern so the documentation for GPGME itself provides a good
43 way to start.
44
45 The context structure in GPGME is mapped to a Context object in
46 GpgMEpp. Additional convienience code provides Data objects and
47 a Dataprovider interface that can be used to implement GPGME's
48 data with any subclass by implementing the right callbacks.
49
50 EditInteractor subclasses provide ready to use classes for
51 common --edit-key tasks. You can implement your own editinteractor
52 classes by implementing the EditInteractor interface and using
53 your subclass as an interactor in the edit function.
54
55 Example to set the ownertrust of a key:
56
57     /* Create an edit interactor */
58     EditInteractor *ei = new GpgSetOwnerTrustEditInteractor(Key::Ultimate);
59     /* Obtain a Context */
60     Context *ctx = Context::createForProtocol(Protocol::OpenPGP);
61     /* Create an in memory data object */
62     Data data;
63     /* Start the edit on some key previously obtained. */
64     Error e = ctx->edit(key, std::unique_ptr<EditInteractor>(ei), data);
65     /* Errors provide boolean comparison */
66     if (!e)
67         ...
68     /* Delete the context */
69     delete ctx;
70
71 Examples / Tests
72 ----------------
73
74 GpgMEpp is tested through the Qt API. You can refer to the
75 tests in qt/tests for examples of usage or refer to
76 the actual QGpgME*Job.cpp implementations which rely
77 on GpgMEpp and should cover most use cases.
78
79 Hacking
80 -------
81
82 GpgMEpp follows KDE Coding styles. See:
83 https://techbase.kde.org/Policies/Frameworks_Coding_Style
84 for more info.
85
86 License
87 -------
88 GPGMEpp is free software; you can redistribute it and/or
89 modify it under the terms of the GNU Library General Public
90 License as published by the Free Software Foundation; either
91 version 2 of the License, or (at your option) any later version.
92
93 GPGMEpp is distributed in the hope that it will be useful,
94 but WITHOUT ANY WARRANTY; without even the implied warranty of
95 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
96 GNU Library General Public License for more details.
97
98 You should have received a copy of the GNU Library General Public License
99 along with GPGME++; see the file COPYING.LIB.  If not, write to the
100 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
101 Boston, MA 02110-1301, USA.