131 lines
4.9 KiB
Plaintext
131 lines
4.9 KiB
Plaintext
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.
|