diff options
Diffstat (limited to 'lang/qt/README')
| -rw-r--r-- | lang/qt/README | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/lang/qt/README b/lang/qt/README new file mode 100644 index 0000000..6360a5b --- /dev/null +++ b/lang/qt/README @@ -0,0 +1,130 @@ +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 +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. |