From 66febf9942c321d30b8770f6aa6cd6ce2315d34f Mon Sep 17 00:00:00 2001 From: Andre Heinecke Date: Mon, 19 Sep 2016 14:09:19 +0200 Subject: [PATCH] cpp: Improve README * lang/cpp/README: Add more content, move license to bottom. --- lang/cpp/README | 85 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 63 insertions(+), 22 deletions(-) diff --git a/lang/cpp/README b/lang/cpp/README index d5f4093b..b9a48da1 100644 --- a/lang/cpp/README +++ b/lang/cpp/README @@ -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 -in KDE 4 it was part of kdepimlibs/gpgme++ for KF5 Gpgmepp was -renamed to KF5GpgMEpp and moved into it's own repository. +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. + +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(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.