qt: Improve README
* lang/qt/README: Add more content. Clearly note license difference.
This commit is contained in:
Andre Heinecke
parent
66febf9942
commit
3f92253e0e
120
lang/qt/README
120
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user