[git] GPGME - branch, master, updated. gpgme-1.6.0-385-g3f92253
by Andre Heinecke
cvs at cvs.gnupg.org
Mon Sep 19 14:10:16 CEST 2016
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GnuPG Made Easy".
The branch, master has been updated
via 3f92253e0e476d77aa11463bc51ade367985855f (commit)
via 66febf9942c321d30b8770f6aa6cd6ce2315d34f (commit)
from 65f6f68f0966346bf48475a04ca5c73a2828b6c4 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 3f92253e0e476d77aa11463bc51ade367985855f
Author: Andre Heinecke <aheinecke at intevation.de>
Date: Mon Sep 19 14:09:44 2016 +0200
qt: Improve README
* lang/qt/README: Add more content. Clearly note license difference.
diff --git a/lang/qt/README b/lang/qt/README
index f624f60..6360a5b 100644
--- a/lang/qt/README
+++ b/lang/qt/README
@@ -1,7 +1,109 @@
-Qt API bindings/wrapper for gpgme
-----------------------------------------
-Based on KF5gpgmepp QGpgme and libkleo/backends/qgpgme
+Qt API bindings/wrapper for GPGME
+---------------------------------
+Based on KF5gpgmepp QGpgME and libkleo/backends/qgpgme
+Please note that QGpgME has a different license (GPL only)
+then GPGME itself. See the License secion in this
+document for more information.
+
+Overview
+--------
+QGpgme provides a very high level Qt API around GpgMEpp.
+As such it depends on GpgMEpp additionally to GpgME.
+
+There are two general concepts in QGpgME. Data abstraction
+through GpgMEpp's Dataprovider interface and the Job pattern.
+
+Data can be provided with QByteArrayDataProvider or
+QIODeviceDataProvider which can be constructed from their
+respective types. This means you can pass a QFile, QProcess,
+QString, etc.. directly to GPGME.
+
+To provide a stable API / ABI and because of historic reasons
+in libkleo (Where QGpgME was originally developed as an abstract
+crypto backend) QGpgME only provides abstract interfaces as
+public API while the actual implementation happens in the
+private QGpgME prefixed classes.
+
+Usage
+-----
+
+To use QGpgME first you need to obtain a Protocol class
+either for CMS (S/MIME) or OpenPGP. This Protocol class
+can then be used to create a Job.
+
+Each Job can be started asynchronusly and emits a result
+signal when done. The jobs are deleted automatically
+with QObject::deleteLater so they can be started without
+result handlers.
+
+The result signal provides a tuple of objects with the
+appropiate result information for this job. For historic
+reasons each result signal also includes an AuditLog
+and an AuditLog Error. These are only useful for
+S/MIME signature validation but are part of other jobs
+for API stability reasons.
+
+Some jobs like the verification or decryption jobs have
+dedicated result classes. Each result class at least
+has the member function error() that can be used
+to check if a job failed. Additionally errors are emited
+in the result signal.
+
+Jobs also provide progress signal whenever GnuPG emits
+a progress status line.
+
+Most jobs also provide a way synchronusly execute them.
+Please not that synchronus use does not cause the autodeletion
+to take place so you have to manually delete them.
+
+Async usage:
+
+ /* Create a job */
+ EncryptJob *job = openpgp()->encryptJob(/*ASCII Armor */false, /* Textmode */ false);
+ /* Connect something to the result signal */
+ connect(job, &EncryptJob::result, this, [] (const GpgME::EncryptionResult &result,
+ const QByteArray &cipherText,
+ const QString,
+ const GpgME::Error) {
+ /* Handle the result / do something with the ciphertext */
+ });
+ /* Start the job */
+ job->start(keys, inptr, outptr, Context::AlwaysTrust);
+ /* Do not delete the job as it is autodeleted. */
+
+Syncronus usage:
+
+ /* Create a job */
+ KeyListJob *listjob = openpgp()->keyListJob(false, false, false);
+ /* Prepare result vector */
+ std::vector<Key> keys;
+ /* Execute it synchronusly */
+ KeyListResult result = listjob->exec(QStringList() << QStringLiteral("alfa at example.net"),
+ false, keys);
+ /* Delete the job */
+ delete listjob;
+ /* Work with the result */
+
+See the generated documentation for more info on the classes
+in QGpgME. (Subdir doc)
+
+Examples / Tests
+----------------
+
+The tests in the tests subdir can be used to get a better
+idea of QGpgME's usage. They also serve to test the C++
+API. Kleopatra and KMails Messagelib also make extensive
+use of QGpgME and can be used as further examples.
+
+Hacking
+-------
+QGpgME comes from a KDE background. As such it does not use
+GNU Coding styles but KDE Coding styles. See:
+https://techbase.kde.org/Policies/Frameworks_Coding_Style
+
+License
+-------
QGpgME is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the
@@ -26,15 +128,3 @@ Qt. If you modify this file, you may extend this exception to
your version of the file, but you are not obligated to do so. If
you do not wish to do so, delete this exception statement from
your version.
-
-Overview
---------
-QGpgme provides Qt API bindings around Gpgmepp. It depends on Gpgmepp.
-
-See the generated documentation for more info.
-
-Hacking
--------
-QGpgME comes from a KDE background. As such it does not use
-GNU Coding styles but KDE Coding styles. See:
-https://techbase.kde.org/Policies/Frameworks_Coding_Style
commit 66febf9942c321d30b8770f6aa6cd6ce2315d34f
Author: Andre Heinecke <aheinecke at intevation.de>
Date: Mon Sep 19 14:09:19 2016 +0200
cpp: Improve README
* lang/cpp/README: Add more content, move license to bottom.
diff --git a/lang/cpp/README b/lang/cpp/README
index d5f4093..b9a48da 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.
+
+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.
-----------------------------------------------------------------------
Summary of changes:
lang/cpp/README | 85 ++++++++++++++++++++++++++++-----------
lang/qt/README | 120 +++++++++++++++++++++++++++++++++++++++++++++++++-------
2 files changed, 168 insertions(+), 37 deletions(-)
hooks/post-receive
--
GnuPG Made Easy
http://git.gnupg.org
More information about the Gnupg-commits
mailing list