From 3f92253e0e476d77aa11463bc51ade367985855f Mon Sep 17 00:00:00 2001
From: Andre Heinecke <aheinecke@intevation.de>
Date: Mon, 19 Sep 2016 14:09:44 +0200
Subject: [PATCH] qt: Improve README

* lang/qt/README: Add more content. Clearly note license difference.
---
 lang/qt/README | 120 ++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 105 insertions(+), 15 deletions(-)

diff --git a/lang/qt/README b/lang/qt/README
index f624f601..6360a5be 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@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