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

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 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. */

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.