File indexing completed on 2024-06-23 05:14:12

 /* -*- mode: c++; c-basic-offset:4 -*-
     uiserver/assuancommand.h
 
     This file is part of Kleopatra, the KDE keymanager
     SPDX-FileCopyrightText: 2007 Klarälvdalens Datakonsult AB
 
     SPDX-License-Identifier: GPL-2.0-or-later
 */
 
 #pragma once
 
 #include <utils/pimpl_ptr.h>
 #include <utils/types.h>
 
 #include <gpgme++/error.h>
 #include <gpgme++/global.h>
 
 #include <gpg-error.h>
 
 #include <KMime/Types>
 
 #include <qwindowdefs.h> // for WId
 
 #include <map>
 #include <memory>
 #include <string>
 #include <vector>
 
 class QVariant;
 class QObject;
 #include <QStringList>
 
 struct assuan_context_s;
 
 namespace Kleo
 {
 
 class Input;
 class Output;
 
 class AssuanCommandFactory;
 
 /*!
   \brief Base class for GnuPG UI Server commands
 
   \note large parts of this are outdated by now!
 
   <h3>Implementing a new AssuanCommand</h3>
 
   You do not directly inherit AssuanCommand, unless you want to
   deal with implementing low-level, repetitive things like name()
   in terms of staticName(). Assuming you don't, then you inherit
   your command class from AssuanCommandMixin, passing your class
   as the template argument to AssuanCommandMixin, like this:
 
   \code
   class MyFooCommand : public AssuanCommandMixin<MyFooCommand> {
   \endcode
   (http://en.wikipedia.org/wiki/Curiously_recurring_template_pattern)
 
   You then choose a command name, and return that from the static
   method staticName(), which is by convention queried by both
   AssuanCommandMixin<> and GenericAssuanCommandFactory<>:
 
   \code
       static const char * staticName() { return "MYFOO"; }
   \endcode
 
   The string should be all-uppercase by convention, but the
   UiServer implementation doesn't enforce this.
 
   The next step is to implement start(), the starting point of
   command execution:
 
   <h3>Executing the command</h3>
 
   \code
       int start( const std::string & line ) {
   \endcode
 
   This should set everything up and check the parameters in \a
   line and any options this command understands. If there's an
   error, choose one of the gpg-error codes and create a
   gpg_error_t from it using the protected makeError() function:
 
   \code
           return makeError( GPG_ERR_NOT_IMPLEMENTED );
   \endcode
 
   But usually, you will want to create a dialog, or call some
   GpgME function from here. In case of errors from GpgME, you
   shouldn't pipe them through makeError(), but return them
   as-is. This will preserve the error source. Error created using
   makeError() will have Kleopatra as their error source, so watch
   out what you're doing :)
 
   In addition to options and the command line, your command might
   require <em>bulk data</em> input or output. That's what the bulk
   input and output channels are for. You can check whether the
   client handed you an input channel by checking that
   bulkInputDevice() isn't NULL, likewise for bulkOutputDevice().
 
   If everything is ok, you return 0. This indicates to the client
   that the command has been accepted and is now in progress.
 
   In this mode (start() returned 0), there are a bunch of options
   for your command to do. Some commands may require additional
   information from the client. The options passed to start() are
   designed to be persistent across commands, and rather limited in
   length (there's a strict line length limit in the assuan
   protocol with no line continuation mechanism). The same is true
   for command line arguments, which, in addition, you have to
   parse yourself. Those usually apply only to this command, and
   not to following ones.
 
   If you need data that might be larger than the line length
   limit, you can either expect it on the bulkInputDevice(), or, if
   you have the need for more than one such data channel, or the
   data is optional or conditional on some condition that can only
   be determined during command execution, you can \em inquire the
   missing information from the client.
 
   As an example, a VERIFY command would expect the signed data on
   the bulkInputDevice(). But if the input stream doesn't contain
   an embedded (opaque) signature, indicating a \em detached
   signature, it would go and inquire that data from the
   client. Here's how it works:
 
   \code
   const int err = inquire( "DETACHED_SIGNATURE",
                            this, SLOT(slotDetachedSignature(int,QByteArray,QByteArray)) );
   if ( err )
       done( err );
   \endcode
 
   This should be self-explanatory: You give a slot to call when
   the data has arrived. The slot's first argument is an error
   code. The second the data (if any), and the third is just
   repeating what you gave as inquire()'s first argument. As usual,
   you can leave argument off of the end, if you are not interested
   in them.
 
   You can do as many inquiries as you want, but only one at a
   time.
 
   You should periodically send status updates to the client. You do
   that by calling sendStatus().
 
   Once your command has finished executing, call done(). If it's
   with an error code, call done(err) like above. <b>Do not
   forget to call done() when done!</b>. It will close
   bulkInputDevice(), bulkOutputDevice(), and send an OK or ERR
   message back to the client.
 
   At that point, your command has finished executing, and a new
   one can be accepted, or the connection closed.
 
   Apropos connection closed. The only way for the client to cancel
   an operation is to shut down the connection. In this case, the
   canceled() function will be called. At that point, the
   connection to the client will have been broken already, and all
   you can do is pack your things and go down gracefully.
 
   If _you_ detect that the user has canceled (your dialog contains
   a cancel button, doesn't it?), then you should instead call
   done( GPG_ERR_CANCELED ), like for normal operation.
 
   <h3>Registering the command with UiServer</h3>
 
   To register a command, you implement a AssuanCommandFactory for
   your AssuanCommand subclass, and register it with the
   UiServer. This can be made considerably easier using
   GenericAssuanCommandFactory:
 
   \code
   UiServer server;
   server.registerCommandFactory( shared_ptr<AssuanCommandFactory>( new GenericAssuanCommandFactory<MyFooCommand> ) );
   // more registerCommandFactory calls...
   server.start();
   \endcode
 
 */
 class AssuanCommand : public ExecutionContext, public std::enable_shared_from_this<AssuanCommand>
 {
     // defined in assuanserverconnection.cpp!
 public:
     AssuanCommand();
     ~AssuanCommand() override;
 
     int start();
     void canceled();
 
     virtual const char *name() const = 0;
 
     class Memento
     {
     public:
         virtual ~Memento()
         {
         }
     };
 
     template<typename T>
     class TypedMemento : public Memento
     {
         T m_t;
 
     public:
         explicit TypedMemento(const T &t)
             : m_t(t)
         {
         }
 
         const T &get() const
         {
             return m_t;
         }
         T &get()
         {
             return m_t;
         }
     };
 
     template<typename T>
     static std::shared_ptr<TypedMemento<T>> make_typed_memento(const T &t)
     {
         return std::shared_ptr<TypedMemento<T>>(new TypedMemento<T>(t));
     }
 
     static int makeError(int code);
 
     // convenience methods:
     enum Mode { NoMode, EMail, FileManager };
     Mode checkMode() const;
 
     enum CheckProtocolOption {
         AllowProtocolMissing = 0x01,
     };
 
     GpgME::Protocol checkProtocol(Mode mode, int options = 0) const;
 
     void applyWindowID(QWidget *w) const override
     {
         doApplyWindowID(w);
     }
     WId parentWId() const;
 
     void setNohup(bool on);
     bool isNohup() const;
     bool isDone() const;
 
     QString sessionTitle() const;
     unsigned int sessionId() const;
 
     bool informativeRecipients() const;
     bool informativeSenders() const;
 
     const std::vector<KMime::Types::Mailbox> &recipients() const;
     const std::vector<KMime::Types::Mailbox> &senders() const;
 
     bool hasMemento(const QByteArray &tag) const;
     std::shared_ptr<Memento> memento(const QByteArray &tag) const;
     template<typename T>
     std::shared_ptr<T> mementoAs(const QByteArray &tag) const
     {
         return std::dynamic_pointer_cast<T>(this->memento(tag));
     }
     QByteArray registerMemento(const std::shared_ptr<Memento> &mem);
     QByteArray registerMemento(const QByteArray &tag, const std::shared_ptr<Memento> &mem);
     void removeMemento(const QByteArray &tag);
     template<typename T>
     T mementoContent(const QByteArray &tag) const
     {
         if (std::shared_ptr<TypedMemento<T>> m = mementoAs<TypedMemento<T>>(tag)) {
             return m->get();
         } else {
             return T();
         }
     }
 
     bool hasOption(const char *opt) const;
     QVariant option(const char *opt) const;
     const std::map<std::string, QVariant> &options() const;
 
     const std::vector<std::shared_ptr<Input>> &inputs() const;
     const std::vector<std::shared_ptr<Input>> &messages() const;
     const std::vector<std::shared_ptr<Output>> &outputs() const;
 
     QStringList fileNames() const;
     unsigned int numFiles() const;
 
     void sendStatus(const char *keyword, const QString &text);
     void sendStatusEncoded(const char *keyword, const std::string &text);
     void sendData(const QByteArray &data, bool moreToCome = false);
 
     int inquire(const char *keyword, QObject *receiver, const char *slot, unsigned int maxSize = 0);
 
     void done(const GpgME::Error &err = GpgME::Error());
     void done(const GpgME::Error &err, const QString &details);
     void done(int err)
     {
         done(GpgME::Error(err));
     }
     void done(int err, const QString &details)
     {
         done(GpgME::Error(err), details);
     }
 
 private:
     virtual void doCanceled() = 0;
     virtual int doStart() = 0;
 
 private:
     void doApplyWindowID(QWidget *w) const;
 
 private:
     const std::map<QByteArray, std::shared_ptr<Memento>> &mementos() const;
 
 private:
     friend class ::Kleo::AssuanCommandFactory;
     class Private;
     kdtools::pimpl_ptr<Private> d;
 };
 
 class AssuanCommandFactory
 {
 public:
     virtual ~AssuanCommandFactory()
     {
     }
 
     virtual std::shared_ptr<AssuanCommand> create() const = 0;
     virtual const char *name() const = 0;
 
     using _Handler = gpg_error_t (*)(assuan_context_s *, char *);
     virtual _Handler _handler() const = 0;
 
     static gpg_error_t _handle(assuan_context_s *, char *, const char *);
 };
 
 template<typename Command>
 class GenericAssuanCommandFactory : public AssuanCommandFactory
 {
     AssuanCommandFactory::_Handler _handler() const override
     {
         return &GenericAssuanCommandFactory::_handle;
     }
     static gpg_error_t _handle(assuan_context_s *_ctx, char *_line)
     {
         return AssuanCommandFactory::_handle(_ctx, _line, Command::staticName());
     }
     std::shared_ptr<AssuanCommand> create() const override
     {
         return make();
     }
     const char *name() const override
     {
         return Command::staticName();
     }
 
 public:
     static std::shared_ptr<Command> make()
     {
         return std::shared_ptr<Command>(new Command);
     }
 };
 
 template<typename Derived, typename Base = AssuanCommand>
 class AssuanCommandMixin : public Base
 {
 protected:
     /* reimp */ const char *name() const override
     {
         return Derived::staticName();
     }
 };
 
 }