assuancommand.h
No OneTemporary
Actions

Size

10 KB

Subscribers

None

assuancommand.h
View Options

	/*
	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/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;
	const std::unique_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();
	}
	};

	}

File Metadata

Mime Type: text/x-c++
Expires: Sat, Nov 29, 7:08 AM (1 d, 22 h)
Storage Engine: local-disk
Storage Format: Raw Data
Storage Handle: c3/ab/57df07fb42f49c91a5093fda3632

assuancommand.hNo OneTemporaryActions

assuancommand.hView Options

File Metadata

Event Timeline

assuancommand.h
No OneTemporary
Actions

assuancommand.h
View Options