File indexing completed on 2022-03-25 15:53:41

0001 /*
0002     SPDX-FileCopyrightText: 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2016 Rolf Eike Beer <kde@opensource.sf-tec.de>
0003     SPDX-License-Identifier: GPL-2.0-or-later
0004 */
0005 #ifndef GPGPROC_H
0006 #define GPGPROC_H
0007 
0008 #include "klinebufferedprocess.h"
0009 
0010 #include <QByteArray>
0011 #include <QString>
0012 #include <QStringList>
0013 
0014 
0015 /**
0016  * @brief A interface to GnuPG handling UTF8 recoding correctly
0017  *
0018  * This class handles the GnuPG formatted UTF8 output correctly.
0019  * GnuPG recodes some characters as \\xnn where nn is the hex representation
0020  * of the character. This can't be fixed up simply when using QString as
0021  * QString already did it's own UTF8 conversion. Therefore we replace this
0022  * sequences by their corresponding character so QString will work just fine.
0023  *
0024  * As we know that GnuPG limits it's columns by QLatin1Char( ':' ) we skip \\x3a. Since this
0025  * is an ascii character (single byte) the replacement can be done later without
0026  * problems after the line has been split into pieces.
0027  *
0028  * @author Rolf Eike Beer
0029  */
0030 class GPGProc : public KLineBufferedProcess
0031 {
0032     Q_OBJECT
0033 
0034 public:
0035     /**
0036      * Constructor
0037      * @param parent parent object
0038      * @param binary path to GnuPG binary or QString() to use the configured
0039      */
0040     explicit GPGProc(QObject *parent = nullptr, const QString &binary = QString());
0041 
0042     /**
0043      * Destructor
0044      */
0045     ~GPGProc() override;
0046 
0047     /**
0048      *  Starts the process
0049      */
0050     void start();
0051 
0052     /**
0053      * Reads a line of text (excluding '\\n').
0054      *
0055      * Use readln() in response to a readReady() signal.
0056      * You may use it multiple times if more than one line of data is
0057      * available.
0058      *
0059      * readln() never blocks.
0060      *
0061      * @param line is used to store the line that was read.
0062      * @param colons recode also colons
0063      * @return the number of characters read, or -1 if no data is available.
0064      */
0065     int readln(QString &line, const bool colons = false);
0066 
0067     /**
0068      * Reads a line of text and splits it into parts.
0069      *
0070      * Use readln() in response to a readReady() signal.
0071      * You may use it multiple times if more than one line of data is
0072      * available.
0073      *
0074      * readln() never blocks.
0075      *
0076      * @param l is used to store the parts of the line that was read.
0077      * @return the number of characters read, or -1 if no data is available.
0078      */
0079     int readln(QStringList &l);
0080 
0081     /**
0082      * Recode a line from GnuPG encoding
0083      *
0084      * @param a data to recode
0085      * @param colons recode also colons
0086      * @param codec the name of the new encoding. The default encoding is utf8.
0087      * @return recoded string
0088      */
0089     static QString recode(QByteArray a, const bool colons = true, const QByteArray &codec = QByteArray());
0090 
0091     /**
0092      * @brief sets the codec used to translate the incoming data
0093      * @param codec the name of the new codec
0094      * @return if the new codec has been accepted
0095      *
0096      * The default codec is utf8. If the given codec is not known to
0097      * QTextCodec the method will return false.
0098      */
0099     bool setCodec(const QByteArray &codec);
0100 
0101     /**
0102      * Reset the class to the state it had right after creation
0103      * @param binary path to GnuPG binary or empty string to use the configured one
0104      */
0105     void resetProcess(const QString &binary = QString());
0106 
0107     /**
0108      * @brief parse GnuPG version string and return version as number
0109      * @param vstr version string
0110      * @return -1 if vstr is empty, -2 on parse error, parsed number on success
0111      *
0112      * The version string must be in format A.B.C with A, B, and C numbers. The
0113      * returned number is A * 65536 + B * 256 + C.
0114      */
0115     static int gpgVersion(const QString &vstr);
0116     /**
0117      * @brief get the GnuPG version string of the given binary
0118      * @param binary name or path to GnuPG binary
0119      * @return version string or empty string on error
0120      *
0121      * This starts a GnuPG process and asks the binary for version information.
0122      * The returned string is the version information without any leading text.
0123      */
0124     static QString gpgVersionString(const QString &binary);
0125 
0126     /**
0127      * @brief find users GnuPG directory
0128      * @param binary name or path to GnuPG binary
0129      * @return path to directory
0130      *
0131      * Use this function to find out where GnuPG would store it's configuration
0132      * and data files. The returned path always ends with a '/'.
0133      */
0134     static QString getGpgHome(const QString &binary);
0135 
0136     /**
0137      * @brief get arguments to set the configuration file and home directory
0138      * @param binary name or path to GnuPG binary
0139      * @return GnuPG argument list
0140      */
0141     static QStringList getGpgHomeArguments(const QString &binary);
0142 
0143     /**
0144      * @brief return a list of the public key algorithms GnuPG announces support for
0145      * @param binary name or path to GnuPG binary
0146      * @return list of algorithm names
0147      *
0148      * All '?' entries are removed.
0149      */
0150     static QStringList getGpgPubkeyAlgorithms(const QString &binary);
0151 
0152     /**
0153      * @brief run GnuPG and check if it complains about anything
0154      * @param binary the GnuPG binary to run
0155      * @return the error message GnuPG gave out (if any)
0156      */
0157     static QString getGpgStartupError(const QString &binary);
0158 
0159     /**
0160      * @brief run GnuPG and let it return it's config output
0161      * @param binary the GnuPG binary to run
0162      * @param key if only fields of a given type should be returned
0163      * @return all matching fields
0164      *
0165      * In case a key is given the key is already removed from the
0166      * returned lines.
0167      */
0168     static QStringList getGgpParsedConfig(const QString &binary, const QByteArray &key = QByteArray());
0169 Q_SIGNALS:
0170     /**
0171      * Emitted when the process is ready for reading.
0172      * The signal is only emitted if at least one complete line of data is ready.
0173      */
0174     void readReady();
0175 
0176     /**
0177      * Emitted when the process has finished
0178      */
0179     void processExited();
0180 
0181 private:
0182     QByteArray m_codec;
0183 };
0184 
0185 #endif // GPGPROC_H