6360a5be5de622d3c79ae5e4ebd1254cd9d8c96e
[gpgme.git] / lang / qt / README
1 Qt API bindings/wrapper for GPGME
2 ---------------------------------
3 Based on KF5gpgmepp QGpgME and libkleo/backends/qgpgme
4
5 Please note that QGpgME has a different license (GPL only)
6 then GPGME itself. See the License secion in this
7 document for more information.
8
9 Overview
10 --------
11 QGpgme provides a very high level Qt API around GpgMEpp.
12 As such it depends on GpgMEpp additionally to GpgME.
13
14 There are two general concepts in QGpgME. Data abstraction
15 through GpgMEpp's Dataprovider interface and the Job pattern.
16
17 Data can be provided with QByteArrayDataProvider or
18 QIODeviceDataProvider which can be constructed from their
19 respective types. This means you can pass a QFile, QProcess,
20 QString, etc.. directly to GPGME.
21
22 To provide a stable API / ABI and because of historic reasons
23 in libkleo (Where QGpgME was originally developed as an abstract
24 crypto backend) QGpgME only provides abstract interfaces as
25 public API while the actual implementation happens in the
26 private QGpgME prefixed classes.
27
28 Usage
29 -----
30
31 To use QGpgME first you need to obtain a Protocol class
32 either for CMS (S/MIME) or OpenPGP. This Protocol class
33 can then be used to create a Job.
34
35 Each Job can be started asynchronusly and emits a result
36 signal when done. The jobs are deleted automatically
37 with QObject::deleteLater so they can be started without
38 result handlers.
39
40 The result signal provides a tuple of objects with the
41 appropiate result information for this job. For historic
42 reasons each result signal also includes an AuditLog
43 and an AuditLog Error. These are only useful for
44 S/MIME signature validation but are part of other jobs
45 for API stability reasons.
46
47 Some jobs like the verification or decryption jobs have
48 dedicated result classes. Each result class at least
49 has the member function error() that can be used
50 to check if a job failed. Additionally errors are emited
51 in the result signal.
52
53 Jobs also provide progress signal whenever GnuPG emits
54 a progress status line.
55
56 Most jobs also provide a way synchronusly execute them.
57 Please not that synchronus use does not cause the autodeletion
58 to take place so you have to manually delete them.
59
60 Async usage:
61
62     /* Create a job */
63     EncryptJob *job = openpgp()->encryptJob(/*ASCII Armor */false, /* Textmode */ false);
64     /* Connect something to the result signal */
65     connect(job, &EncryptJob::result, this, [] (const GpgME::EncryptionResult &result,
66                                                 const QByteArray &cipherText,
67                                                 const QString,
68                                                 const GpgME::Error) {
69         /* Handle the result / do something with the ciphertext */
70      });
71     /* Start the job */
72     job->start(keys, inptr, outptr, Context::AlwaysTrust);
73     /* Do not delete the job as it is autodeleted. */
74
75 Syncronus usage:
76
77     /* Create a job */
78     KeyListJob *listjob = openpgp()->keyListJob(false, false, false);
79     /* Prepare result vector */
80     std::vector<Key> keys;
81     /* Execute it synchronusly */
82     KeyListResult result = listjob->exec(QStringList() << QStringLiteral("alfa@example.net"),
83                                          false, keys);
84     /* Delete the job */
85     delete listjob;
86     /* Work with the result */
87
88 See the generated documentation for more info on the classes
89 in QGpgME. (Subdir doc)
90
91 Examples / Tests
92 ----------------
93
94 The tests in the tests subdir can be used to get a better
95 idea of QGpgME's usage. They also serve to test the C++
96 API. Kleopatra and KMails Messagelib also make extensive
97 use of QGpgME and can be used as further examples.
98
99 Hacking
100 -------
101 QGpgME comes from a KDE background. As such it does not use
102 GNU Coding styles but KDE Coding styles. See:
103 https://techbase.kde.org/Policies/Frameworks_Coding_Style
104
105 License
106 -------
107 QGpgME is free software; you can redistribute it and/or
108 modify it under the terms of the GNU General Public License as
109 published by the Free Software Foundation; either version 2 of the
110 License, or (at your option) any later version.
111
112 QGpgME is distributed in the hope that it will be useful,
113 but WITHOUT ANY WARRANTY; without even the implied warranty of
114 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
115 General Public License for more details.
116
117 You should have received a copy of the GNU General Public License
118 along with this program; if not, write to the Free Software
119 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
120
121 In addition, as a special exception, the copyright holders give
122 permission to link the code of this program with any edition of
123 the Qt library by Trolltech AS, Norway (or with modified versions
124 of Qt that use the same license as Qt), and distribute linked
125 combinations including the two.  You must obey the GNU General
126 Public License in all respects for all of the code used other than
127 Qt.  If you modify this file, you may extend this exception to
128 your version of the file, but you are not obligated to do so.  If
129 you do not wish to do so, delete this exception statement from
130 your version.