gpgme/lang/cpp/README

GpgME++ - C++ bindings/wrapper for GPGME
----------------------------------------
Based on KF5gpgmepp

Overview
--------

GpgME++ is a C++ wrapper (or C++ bindings) for the GnuPG project's
gpgme (GnuPG Made Easy) library, version 0.4.4 and later.

It is fairly complete, with some minor things still missing (in
particular, the key edit interface).

The design principles of this library are as follows:

1. A value-based interface (most clases are implicitly shared)
2. Callbacks are replaced by C++ interfaces (classes with only
   abstract methods).
3. No exceptions are thrown
4. There is (as yet) no explicit support for multi-threaded use
   (other than what gpgme itself provides; most notably the
   refcounting for implicit sharing is not thread-safe)
5. To avoid binary incompatible interface changes, we make
   extensive use of the d-pointer pattern and avoid virtual
   methods; any polymorphism present is already provided by gpgme
   itself, anyway (see e.g. Data). A notable exception of the
   no-virtuals rule is the use of abstract classes to cover
   C-callbacks.
6. Use of STL containers for improved memory management and
   dealing with lists.
7. Complete abstraction of the C-API so "gpgme.h" should not
   be needed in your project using GpgME++.
8. Abstraction of GnuPG's edit-key interface by prepared
   Editinteractor classes.

GpgME++ was originally developed as part of the KDEPIM community.

Usage
-----

The usage pattern of GpgME++ closely follows GPGMEs core usage
pattern so the documentation for GPGME itself provides a good
way to start.

The context structure in GPGME is mapped to a Context object in
GpgME++. Additional convenience code provides Data objects and
a Dataprovider interface that can be used to implement GPGME's
data with any subclass by implementing the right callbacks.

EditInteractor subclasses provide ready to use classes for
common --edit-key tasks. You can implement your own editinteractor
classes by implementing the EditInteractor interface and using
your subclass as an interactor in the edit function.

Example to set the ownertrust of a key:

    /* Create an edit interactor */
    EditInteractor *ei = new GpgSetOwnerTrustEditInteractor(Key::Ultimate);
    /* Obtain a Context */
    Context *ctx = Context::createForProtocol(Protocol::OpenPGP);
    /* Create an in memory data object */
    Data data;
    /* Start the edit on some key previously obtained. */
    Error e = ctx->edit(key, std::unique_ptr<EditInteractor>(ei), data);
    /* Errors provide boolean comparison */
    if (!e)
        ...
    /* Delete the context */
    delete ctx;

Examples / Tests
----------------

GpgME++ is tested through the Qt API. You can refer to the
tests in qt/tests for examples of usage or refer to
the actual QGpgME*Job.cpp implementations which rely
on GpgME++ and should cover most use cases.

Hacking
-------

GpgME++ follows KDE Coding styles. See:
https://techbase.kde.org/Policies/Frameworks_Coding_Style
for more info.

License
-------

GPGME++ is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

GPGME++ is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License
along with GPGME++; see the file COPYING.LIB.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.