kleopatra

Kleo::AssuanCommand

Kleo::AssuanCommand Class Reference

#include <assuancommand.h>

Inheritance diagram for Kleo::AssuanCommand:

[legend]

List of all members.

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 208 of file assuancommand.h.


Public Types
enum	CheckProtocolOption { AllowProtocolMissing = 0x01 }
enum	Mode { NoMode, EMail, FileManager }
Public Member Functions
void	applyWindowID (QWidget *w) const
	AssuanCommand ()
void	canceled ()
Mode	checkMode () const
GpgME::Protocol	checkProtocol (Mode mode, int options=0) const
void	done (int err, const QString &details)
void	done (int err)
void	done (const GpgME::Error &err, const QString &details)
void	done (const GpgME::Error &err=GpgME::Error())
QStringList	fileNames () const
std::vector< boost::shared_ptr < QFile > >	files () const
bool	hasMemento (const QByteArray &tag) const
bool	hasOption (const char *opt) const
QString	heuristicBaseDirectory () 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::map< QByteArray, boost::shared_ptr< Memento > > &	mementos () 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
const std::vector < KMime::Types::Mailbox > &	recipients () const
QByteArray	registerMemento (const QByteArray &tag, const boost::shared_ptr< Memento > &mem)
QByteArray	registerMemento (const boost::shared_ptr< Memento > &mem)
void	releaseFiles ()
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)
QString	sessionTitle () const
void	setNohup (bool on)
int	start ()
virtual	~AssuanCommand ()
Static Public Member Functions
template<typename T>
static boost::shared_ptr < TypedMemento< T > >	make_typed_memento (const T &t)
static int	makeError (int code)
Classes
class	Memento
class	TypedMemento

Member Enumeration Documentation

enum Kleo::AssuanCommand::CheckProtocolOption

Enumerator:

AllowProtocolMissing

Definition at line 245 of file assuancommand.h.

enum Kleo::AssuanCommand::Mode

Enumerator:

NoMode
EMail
FileManager

Definition at line 242 of file assuancommand.h.

Constructor & Destructor Documentation

AssuanCommand::AssuanCommand ( )

Definition at line 939 of file assuanserverconnection.cpp.

AssuanCommand::~AssuanCommand ( ) [virtual]

Definition at line 945 of file assuanserverconnection.cpp.

Member Function Documentation

void Kleo::AssuanCommand::applyWindowID ( QWidget * w ) const [inline, virtual]

Implements Kleo::Crypto::ExecutionContext.

Definition at line 251 of file assuancommand.h.

void AssuanCommand::canceled ( )

Definition at line 974 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 1373 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 1398 of file assuanserverconnection.cpp.

void Kleo::AssuanCommand::done	(	int	err,
		const QString &	details
	)			`[inline]`

Definition at line 309 of file assuancommand.h.

void Kleo::AssuanCommand::done ( int err ) [inline]

Definition at line 308 of file assuancommand.h.

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

Definition at line 1171 of file assuanserverconnection.cpp.

void AssuanCommand::done ( const GpgME::Error & err = GpgME::Error() )

Definition at line 1181 of file assuanserverconnection.cpp.

QStringList AssuanCommand::fileNames ( ) const

Definition at line 1064 of file assuanserverconnection.cpp.

std::vector< shared_ptr< QFile > > AssuanCommand::files ( ) const

Definition at line 1071 of file assuanserverconnection.cpp.

bool AssuanCommand::hasMemento ( const QByteArray & tag ) const

Definition at line 1018 of file assuanserverconnection.cpp.

bool AssuanCommand::hasOption ( const char * opt ) const

Definition at line 984 of file assuanserverconnection.cpp.

QString AssuanCommand::heuristicBaseDirectory ( ) const

Definition at line 1452 of file assuanserverconnection.cpp.

bool AssuanCommand::informativeRecipients ( ) const

Definition at line 1245 of file assuanserverconnection.cpp.

bool AssuanCommand::informativeSenders ( ) const

Definition at line 1241 of file assuanserverconnection.cpp.

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

Definition at line 1052 of file assuanserverconnection.cpp.

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

Definition at line 1147 of file assuanserverconnection.cpp.

bool AssuanCommand::isDone ( ) const

Definition at line 1233 of file assuanserverconnection.cpp.

bool AssuanCommand::isNohup ( ) const

Definition at line 1229 of file assuanserverconnection.cpp.

template<typename T>

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

Definition at line 235 of file assuancommand.h.

int AssuanCommand::makeError ( int code ) [static]

Definition at line 980 of file assuanserverconnection.cpp.

shared_ptr< AssuanCommand::Memento > AssuanCommand::memento ( const QByteArray & tag ) const

Definition at line 1022 of file assuanserverconnection.cpp.

template<typename T>

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

Definition at line 272 of file assuancommand.h.

template<typename T>

T Kleo::AssuanCommand::mementoContent ( const QByteArray & tag ) const [inline]

Definition at line 280 of file assuancommand.h.

const std::map< QByteArray, shared_ptr< AssuanCommand::Memento > > & AssuanCommand::mementos ( ) const

Definition at line 1011 of file assuanserverconnection.cpp.

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

Definition at line 1056 of file assuanserverconnection.cpp.

virtual const char* Kleo::AssuanCommand::name ( ) const [pure virtual]

Implemented in Kleo::AssuanCommandMixin< Kleo::EchoCommand >, Kleo::AssuanCommandMixin< Kleo::DecryptVerifyCommandFilesBase >, Kleo::AssuanCommandMixin< Kleo::SelectCertificateCommand >, Kleo::AssuanCommandMixin< Kleo::DecryptVerifyCommandEMailBase >, Kleo::AssuanCommandMixin< Kleo::PrepEncryptCommand >, Kleo::AssuanCommandMixin< Kleo::EncryptCommand >, Kleo::AssuanCommandMixin< Kleo::SignEncryptFilesCommand >, and Kleo::AssuanCommandMixin< Kleo::SignCommand >.

unsigned int AssuanCommand::numFiles ( ) const

Definition at line 1078 of file assuanserverconnection.cpp.

QVariant AssuanCommand::option ( const char * opt ) const

Definition at line 988 of file assuanserverconnection.cpp.

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

Definition at line 996 of file assuanserverconnection.cpp.

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

Definition at line 1060 of file assuanserverconnection.cpp.

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

Definition at line 1249 of file assuanserverconnection.cpp.

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

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

void AssuanCommand::releaseFiles ( )

Definition at line 1082 of file assuanserverconnection.cpp.

void AssuanCommand::removeMemento ( const QByteArray & tag )

Definition at line 1044 of file assuanserverconnection.cpp.

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

Definition at line 1137 of file assuanserverconnection.cpp.

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

Definition at line 1253 of file assuanserverconnection.cpp.

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

Definition at line 1126 of file assuanserverconnection.cpp.

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

Definition at line 1130 of file assuanserverconnection.cpp.

QString AssuanCommand::sessionTitle ( ) const

Definition at line 1237 of file assuanserverconnection.cpp.

void AssuanCommand::setNohup ( bool on )

Definition at line 1225 of file assuanserverconnection.cpp.

int AssuanCommand::start ( )

Definition at line 949 of file assuanserverconnection.cpp.

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

kleopatra

Kleo::AssuanCommand Class Reference

Detailed Description

Implementing a new AssuanCommand

Executing the command

Registering the command with UiServer

Public Types

Public Member Functions

Static Public Member Functions

Classes

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

kleopatra

kdepim