cpp: Improve README
authorAndre Heinecke <aheinecke@intevation.de>
Mon, 19 Sep 2016 12:09:19 +0000 (14:09 +0200)
committerAndre Heinecke <aheinecke@intevation.de>
Mon, 19 Sep 2016 12:09:19 +0000 (14:09 +0200)
* lang/cpp/README: Add more content, move license to bottom.

lang/cpp/README

index d5f4093..b9a48da 100644 (file)
@@ -1,22 +1,7 @@
-GpgMEpp - C++ bindings/wrapper for gpgme
+GpgMEpp - C++ bindings/wrapper for GPGME
 ----------------------------------------
 Based on KF5gpgmepp
 
-GPGMEpp 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.
-
-GPGMEpp 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.
-
 Overview
 --------
 
@@ -41,20 +26,76 @@ The design principles of this library are as follows:
    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.
+
+GpgMEpp was originally developed as part of the KDEPIM community.
+
+Usage
+-----
+
+The usage pattern of GpgMEpp 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
+GpgMEpp. Additional convienience 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.
 
-GpgMEpp was originally developed as part of the KDEPIM community
-in KDE 4 it was part of kdepimlibs/gpgme++ for KF5 Gpgmepp was
-renamed to KF5GpgMEpp and moved into it's own repository.
+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 comparision */
+    if (!e)
+        ...
+    /* Delete the context */
+    delete ctx;
+
+Examples / Tests
+----------------
+
+GpgMEpp 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 GpgMEpp and should cover most use cases.
 
 Hacking
 -------
+
 GpgMEpp follows KDE Coding styles. See:
 https://techbase.kde.org/Policies/Frameworks_Coding_Style
 for more info.
 
 License
 -------
+GPGMEpp 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.
 
-This library is licensed under the GNU Library General Public
-License (LGPL), just as gpgme is. We feel that using a different
-license than the one gpgme itself uses doesn't make sense.
+GPGMEpp 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.