gpgme/lang/qt/README

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 section 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
appropriate 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 emitted
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 synchronous 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. */

Synchronous 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
License, or (at your option) any later version.

QGpgME 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
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

In addition, as a special exception, the copyright holders give
permission to link the code of this program with any edition of
the Qt library by Trolltech AS, Norway (or with modified versions
of Qt that use the same license as Qt), and distribute linked
combinations including the two.  You must obey the GNU General
Public License in all respects for all of the code used other than
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.