Kleo::AssuanCommand Class Reference

#include <assuancommand.h>

Inheritance diagram for Kleo::AssuanCommand:

Classes
class	Memento
class	TypedMemento

Public Types
enum	CheckProtocolOption { AllowProtocolMissing =0x01 }
enum	Mode { NoMode, EMail, FileManager }

Public Member Functions
	AssuanCommand ()
virtual	~AssuanCommand ()
void	applyWindowID (QWidget *w) const
void	canceled ()
Mode	checkMode () const
GpgME::Protocol	checkProtocol (Mode mode, int options=0) const
void	done (const GpgME::Error &err=GpgME::Error())
void	done (const GpgME::Error &err, const QString &details)
void	done (int err)
void	done (int err, const QString &details)
QStringList	fileNames () const
bool	hasMemento (const QByteArray &tag) const
bool	hasOption (const char *opt) const
bool	informativeRecipients () const
bool	informativeSenders () const
const std::vector < boost::shared_ptr< Input > > &	inputs () const
int	inquire (const char *keyword, QObject *receiver, const char *slot, unsigned int maxSize=0)
bool	isDone () const
bool	isNohup () const
boost::shared_ptr< Memento >	memento (const QByteArray &tag) const
template<typename T >
boost::shared_ptr< T >	mementoAs (const QByteArray &tag) const
template<typename T >
T	mementoContent (const QByteArray &tag) const
const std::vector < boost::shared_ptr< Input > > &	messages () const
virtual const char *	name () const =0
unsigned int	numFiles () const
QVariant	option (const char *opt) const
const std::map< std::string, QVariant > &	options () const
const std::vector < boost::shared_ptr< Output > > &	outputs () const
WId	parentWId () const
const std::vector < KMime::Types::Mailbox > &	recipients () const
QByteArray	registerMemento (const boost::shared_ptr< Memento > &mem)
QByteArray	registerMemento (const QByteArray &tag, const boost::shared_ptr< Memento > &mem)
void	removeMemento (const QByteArray &tag)
void	sendData (const QByteArray &data, bool moreToCome=false)
const std::vector < KMime::Types::Mailbox > &	senders () const
void	sendStatus (const char *keyword, const QString &text)
void	sendStatusEncoded (const char *keyword, const std::string &text)
unsigned int	sessionId () const
QString	sessionTitle () const
void	setNohup (bool on)
int	start ()
Public Member Functions inherited from Kleo::ExecutionContext
virtual	~ExecutionContext ()

Static Public Member Functions
template<typename T >
static boost::shared_ptr < TypedMemento< T > >	make_typed_memento (const T &t)
static int	makeError (int code)

Detailed Description

Base class for GnuPG UI Server commands.

Note

large parts of this are outdated by now!

Implementing a new AssuanCommand

You do not directly inherit AssuanCommand, unless you want to deal with implementing low-level, repetetive 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:

class MyFooCommand : public AssuanCommandMixin<MyFooCommand> {

(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<>:

static const char * staticName() { return "MYFOO"; }

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:

Executing the command

int start( const std::string & line ) {

This should set everything up and check the parameters in 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:

return makeError( GPG_ERR_NOT_IMPLEMENTED );

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 {bulk data} 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 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 detached signature, it would go and inquire that data from the client. Here's how it works:

const int err = inquire( "DETACHED_SIGNATURE",
                         this, SLOT(slotDetachedSignature(int,QByteArray,QByteArray)) );
if ( err )
    done( err );

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 peridocally 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. {Do not forget to call done() when done!}. 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.

Registering the command with UiServer

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:

UiServer server;
server.registerCommandFactory( shared_ptr<AssuanCommandFactory>( new GenericAssuanCommandFactory<MyFooCommand> ) );
// more registerCommandFactory calls...
server.start();

Definition at line 215 of file assuancommand.h.

Member Enumeration Documentation

enum Kleo::AssuanCommand::CheckProtocolOption

Enumerator
AllowProtocolMissing

Definition at line 252 of file assuancommand.h.

enum Kleo::AssuanCommand::Mode

Enumerator
NoMode
EMail
FileManager

Definition at line 249 of file assuancommand.h.

Constructor & Destructor Documentation

AssuanCommand::AssuanCommand

(

)

Definition at line 1097 of file assuanserverconnection.cpp.

AssuanCommand::~AssuanCommand ( )

virtual

Definition at line 1103 of file assuanserverconnection.cpp.

Member Function Documentation

void Kleo::AssuanCommand::applyWindowID ( QWidget *  w ) const

inlinevirtual

Implements Kleo::ExecutionContext.

Definition at line 258 of file assuancommand.h.

void AssuanCommand::canceled

(

)

Definition at line 1132 of file assuanserverconnection.cpp.

AssuanCommand::Mode AssuanCommand::checkMode

(

)

const

Checks the –mode parameter.

Returns

The parameter as an AssuanCommand::Mode enum value.

If no –mode was given, or it's value wasn't recognized, throws an Kleo::Exception.

Definition at line 1501 of file assuanserverconnection.cpp.

GpgME::Protocol AssuanCommand::checkProtocol	(	Mode	mode,
		int	options = 0
	)		const

Checks the –protocol parameter.

Returns

The parameter as a GpgME::Protocol enum value.

If –protocol was given, but has an invalid value, throws an Kleo::Exception.

If no –protocol was given, checks the connection bias, if available, otherwise, in FileManager mode, returns GpgME::UnknownProtocol, but if mode == EMail, throws an Kleo::Exception instead.

Definition at line 1526 of file assuanserverconnection.cpp.

void AssuanCommand::done

(

const GpgME::Error &

err = GpgME::Error()

)

Definition at line 1300 of file assuanserverconnection.cpp.

void AssuanCommand::done	(	const GpgME::Error &	err,
		const QString &	details
	)

Definition at line 1290 of file assuanserverconnection.cpp.

void Kleo::AssuanCommand::done ( int  err )

inline

Definition at line 312 of file assuancommand.h.

void Kleo::AssuanCommand::done ( int  err, const QString &  details  )

inline

Definition at line 313 of file assuancommand.h.

QStringList AssuanCommand::fileNames

(

)

const

Definition at line 1237 of file assuanserverconnection.cpp.

bool AssuanCommand::hasMemento

(

const QByteArray &

tag

)

const

Definition at line 1176 of file assuanserverconnection.cpp.

bool AssuanCommand::hasOption

(

const char *

opt

)

const

Definition at line 1142 of file assuanserverconnection.cpp.

bool AssuanCommand::informativeRecipients

(

)

const

Definition at line 1367 of file assuanserverconnection.cpp.

bool AssuanCommand::informativeSenders

(

)

const

Definition at line 1363 of file assuanserverconnection.cpp.

const std::vector< shared_ptr< Input > > & AssuanCommand::inputs

(

)

const

Definition at line 1225 of file assuanserverconnection.cpp.

int AssuanCommand::inquire	(	const char *	keyword,
		QObject *	receiver,
		const char *	slot,
		unsigned int	maxSize = 0
	)

Definition at line 1266 of file assuanserverconnection.cpp.

bool AssuanCommand::isDone

(

)

const

Definition at line 1351 of file assuanserverconnection.cpp.

bool AssuanCommand::isNohup

(

)

const

Definition at line 1347 of file assuanserverconnection.cpp.

template<typename T >

static boost::shared_ptr< TypedMemento<T> > Kleo::AssuanCommand::make_typed_memento ( const T &  t )

inlinestatic

Definition at line 242 of file assuancommand.h.

int AssuanCommand::makeError ( int  code )

static

Definition at line 1138 of file assuanserverconnection.cpp.

shared_ptr< AssuanCommand::Memento > AssuanCommand::memento

(

const QByteArray &

tag

)

const

Definition at line 1183 of file assuanserverconnection.cpp.

template<typename T >

boost::shared_ptr<T> Kleo::AssuanCommand::mementoAs ( const QByteArray &  tag ) const

inline

Definition at line 279 of file assuancommand.h.

template<typename T >

T Kleo::AssuanCommand::mementoContent ( const QByteArray &  tag ) const

inline

Definition at line 286 of file assuancommand.h.

const std::vector< shared_ptr< Input > > & AssuanCommand::messages

(

)

const

Definition at line 1229 of file assuanserverconnection.cpp.

virtual const char* Kleo::AssuanCommand::name ( ) const

pure virtual

unsigned int AssuanCommand::numFiles

(

)

const

Definition at line 1241 of file assuanserverconnection.cpp.

QVariant AssuanCommand::option

(

const char *

opt

)

const

Definition at line 1146 of file assuanserverconnection.cpp.

const std::map< std::string, QVariant > & AssuanCommand::options

(

)

const

Definition at line 1154 of file assuanserverconnection.cpp.

const std::vector< shared_ptr< Output > > & AssuanCommand::outputs

(

)

const

Definition at line 1233 of file assuanserverconnection.cpp.

WId AssuanCommand::parentWId

(

)

const

Definition at line 1552 of file assuanserverconnection.cpp.

const std::vector< KMime::Types::Mailbox > & AssuanCommand::recipients

(

)

const

Definition at line 1371 of file assuanserverconnection.cpp.

QByteArray AssuanCommand::registerMemento

(

const boost::shared_ptr< Memento > &

mem

)

Definition at line 1198 of file assuanserverconnection.cpp.

QByteArray AssuanCommand::registerMemento	(	const QByteArray &	tag,
		const boost::shared_ptr< Memento > &	mem
	)

Definition at line 1203 of file assuanserverconnection.cpp.

void AssuanCommand::removeMemento

(

const QByteArray &

tag

)

Definition at line 1215 of file assuanserverconnection.cpp.

void AssuanCommand::sendData	(	const QByteArray &	data,
		bool	moreToCome = false
	)

Definition at line 1256 of file assuanserverconnection.cpp.

const std::vector< KMime::Types::Mailbox > & AssuanCommand::senders

(

)

const

Definition at line 1375 of file assuanserverconnection.cpp.

void AssuanCommand::sendStatus	(	const char *	keyword,
		const QString &	text
	)

Definition at line 1245 of file assuanserverconnection.cpp.

void AssuanCommand::sendStatusEncoded	(	const char *	keyword,
		const std::string &	text
	)

Definition at line 1249 of file assuanserverconnection.cpp.

unsigned int AssuanCommand::sessionId

(

)

const

Definition at line 1359 of file assuanserverconnection.cpp.

QString AssuanCommand::sessionTitle

(

)

const

Definition at line 1355 of file assuanserverconnection.cpp.

void AssuanCommand::setNohup

(

bool

on

)

Definition at line 1343 of file assuanserverconnection.cpp.

int AssuanCommand::start

(

)

Definition at line 1107 of file assuanserverconnection.cpp.

---

The documentation for this class was generated from the following files:

• assuancommand.h
• assuanserverconnection.cpp