#include <kgpgtransaction.h>

Inheritance diagram for KGpgTransaction:

Public Types
enum	ts_boolanswer { BA_UNKNOWN = 0, BA_YES = 1, BA_NO = 2 }

enum	ts_hintType { HT_KEYEXPIRED = 0, HT_SIGEXPIRED = 1, HT_NOSECKEY = 2, HT_ENCTO = 3 }

enum	ts_transaction { TS_OK = 0, TS_BAD_PASSPHRASE = 1, TS_MSG_SEQUENCE = 2, TS_USER_ABORTED = 3, TS_INVALID_EMAIL = 4, TS_INPUT_PROCESS_ERROR = 5, TS_COMMON_END = 100 }

Signals
void	done (int result)

void	infoProgress (qulonglong processedAmount, qulonglong totalAmount)

void	statusMessage (const QString &msg)

Public Member Functions
	KGpgTransaction (QObject *parent=0, const bool allowChaining=false)

virtual	~KGpgTransaction ()

void	clearInputTransaction ()

const QString &	getDescription () const

bool	hasInputTransaction () const

void	kill ()

void	setGnuPGHome (const QString &home)

void	setInputTransaction (KGpgTransaction *ta)

void	start ()

int	waitForFinished (const int msecs=-1)

Public Member Functions inherited from QObject
	QObject (QObject *parent)

	QObject (QObject parent, const char name)

virtual	~QObject ()

bool	blockSignals (bool block)

QObject *	child (const char objName, const char inheritsClass, bool recursiveSearch) const

const QObjectList &	children () const

const char *	className () const

bool	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const QObject receiver, const char method)

bool	disconnect (const char signal, const QObject receiver, const char *method)

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QByteArray >	dynamicPropertyNames () const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name) const

QList< T >	findChildren (const QRegExp &regExp) const

QList< T >	findChildren (const QString &name) const

bool	inherits (const char *className) const

void	insertChild (QObject *object)

void	installEventFilter (QObject *filterObj)

bool	isA (const char *className) const

bool	isWidgetType () const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

const char *	name () const

const char *	name (const char *defaultName) const

QString	objectName () const

QObject *	parent () const

QVariant	property (const char *name) const

void	removeChild (QObject *object)

void	removeEventFilter (QObject *obj)

void	setName (const char *name)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval)

QThread *	thread () const

Protected Member Functions
int	addArgument (const QString &arg)

void	addArgumentRef (int *ref)

int	addArguments (const QStringList &args)

void	addIdHint (QString txt)

void	askNewPassphrase (const QString &text)

bool	askPassphrase (const QString &message=QString())

virtual ts_boolanswer	boolQuestion (const QString &line)

virtual ts_boolanswer	confirmOverwrite (KUrl &currentFile)

virtual void	finish ()

QString	getIdHints () const

GPGProc *	getProcess ()

int	getSuccess () const

virtual bool	hintLine (const ts_hintType hint, const QString &args)

void	insertArgument (const int pos, const QString &arg)

void	insertArguments (const int pos, const QStringList &args)

virtual void	newPassphraseEntered ()

virtual bool	nextLine (const QString &line)=0

virtual bool	passphraseReceived ()

virtual bool	passphraseRequested ()

virtual void	postStart ()

virtual bool	preStart ()

void	replaceArgument (const int pos, const QString &arg)

void	setDescription (const QString &description)

void	setSuccess (const int v)

void	unexpectedLine (const QString &line)

void	waitForInputTransaction ()

void	write (const QByteArray &a, const bool lf=true)

void	write (const int i)

Protected Member Functions inherited from QObject
bool	checkConnectArgs (const char signal, const QObject object, const char *method)

virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const char *signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const char *signal)

int	receivers (const char *signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Additional Inherited Members
Static Public Member Functions inherited from QObject
bool	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

bool	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Static Protected Member Functions inherited from QObject
QByteArray	normalizeSignalSlot (const char *signalSlot)

Properties inherited from QObject
	objectName

Detailed Description

Process one GnuPG operation.

This class encapsulates one GnuPG operation. It will care for all interaction with the gpg process. Everything you have to care about is to set up the object properly, call start() and catch the done signal.

This is an abstract base class for specific operations that implements the basic I/O loop, the process setup and interaction and some convenience members to set extra arguments for the process.

If you want to add a new operation create a child class that implements nextLine(). Ususally you also need a constructor that takes some information like the id of the key to modify.

Author: Rolf Eike Beer

Definition at line 44 of file kgpgtransaction.h.

Member Enumeration Documentation

enum KGpgTransaction::ts_boolanswer

result codes for GnuPG boolean questions

These are the possible answers to a boolean question of a GnuPG process.

Enumerator
BA_UNKNOWN	the question is not supported (this is an error)
BA_YES	answer "YES"
BA_NO	answer "NO"

Definition at line 73 of file kgpgtransaction.h.

enum KGpgTransaction::ts_hintType

the known hints sent by GnuPG

Enumerator
HT_KEYEXPIRED	key is expired
HT_SIGEXPIRED	deprecated by GnuPG
HT_NOSECKEY	secret key not available
HT_ENCTO	message is encrypted for this key

Definition at line 81 of file kgpgtransaction.h.

enum KGpgTransaction::ts_transaction

return codes common to many transactions

Every transaction may define additional return codes, which should start at TS_COMMON_END + 1.

Enumerator
TS_OK	everything went fine
TS_BAD_PASSPHRASE	the passphrase was not correct
TS_MSG_SEQUENCE	unexpected sequence of GnuPG messages
TS_USER_ABORTED	the user aborted the transaction
TS_INVALID_EMAIL	the given email address is invalid
TS_INPUT_PROCESS_ERROR	the connected input process returned an error
TS_COMMON_END	placeholder for return values of derived classes

Definition at line 59 of file kgpgtransaction.h.

Constructor & Destructor Documentation

KGpgTransaction::KGpgTransaction	(	QObject *	parent = `0`,
		const bool	allowChaining = `false`
	)

explicit

KGpgTransaction constructor.

Definition at line 118 of file kgpgtransaction.cpp.

KGpgTransaction::~KGpgTransaction ( )

virtual

KGpgTransaction destructor.

Definition at line 127 of file kgpgtransaction.cpp.

Member Function Documentation

int KGpgTransaction::addArgument ( const QString & arg )

protected

add a command line argument to gpg process

Parameters

arg	new argument

Returns: the position of the new argument

This is a convenience function that allows adding one additional argument to the command line of the process. This must be called before start() is called. Usually you will call this from your constructor.

Definition at line 562 of file kgpgtransaction.cpp.

void KGpgTransaction::addArgumentRef ( int * ref )

protected

make sure the reference to a specific argument is kept up to date

Parameters

ref	the value where the position is stored

You might want to keep the position of a specific argument to later be able to repace it easily. In that case put it into this function too so every time someone mofifies the argument list (especially by insertArgument() and insertArguments()) this reference will be kept up to date.

Definition at line 617 of file kgpgtransaction.cpp.

int KGpgTransaction::addArguments ( const QStringList & args )

protected

add command line arguments to gpg process

Parameters

args	new arguments

Returns: the position of the first argument added

This is a convenience function that allows adding additional arguments to the command line of the process. This must be called before start() is called.

Definition at line 572 of file kgpgtransaction.cpp.

void KGpgTransaction::addIdHint ( QString txt )

protected

add a userid hint

Parameters

txt	userid description

Before GnuPG asks for a passphrase it usually sends out a hint message for which key the passphrase will be needed. There may be several hint messages, e.g. if a text was encrypted with multiple keys.

Definition at line 535 of file kgpgtransaction.cpp.

void KGpgTransaction::askNewPassphrase ( const QString & text )

protected

Ask user for passphrase and send it to gpg process.

If the gpg process asks for a new passphrase this function will do all necessary steps for you: ask the user for the passphrase and write it to the gpg process. If the passphrase is wrong the user is prompted again for the correct passphrase. If the user aborts the passphrase entry the gpg process will be killed and the transaction result will be set to TS_USER_ABORTED.

See also: askPassphrase

Definition at line 428 of file kgpgtransaction.cpp.

bool KGpgTransaction::askPassphrase ( const QString & message = QString() )

protected

ask user for passphrase

Parameters

message message to display to the user. If message is empty "Enter passphrase for [UID]" will be used.

Returns: true if the authorization was successful

This function handles user authorization for key operations. It will take care to display the message asking the user for the passphrase and the number of tries left.

Definition at line 623 of file kgpgtransaction.cpp.

KGpgTransaction::ts_boolanswer KGpgTransaction::boolQuestion ( const QString & line )

protectedvirtual

Called for every boolean question GnuPG answers.

Parameters

line	the question GnuPG asked

Returns: what to answer GnuPG

This is called instead of nextLine() if the line contains a boolean question. Returning BA_UNKNOWN will cancel the current transaction and will set the transaction result to TS_MSG_SEQUENCE.

The default implementation will answer BA_UNKNOWN to every question.

Reimplemented in KGpgDelUid, KGpgEditKeyTransaction, KGpgDelSign, KGpgSignUid, KGpgGenerateRevoke, KGpgSignKey, KGpgDelKey, and KGpgChangeTrust.

Definition at line 457 of file kgpgtransaction.cpp.

void KGpgTransaction::clearInputTransaction ( )

tell the process the standard input is no longer connected

If you had connected an input process you need to tell the transaction once this input process is gone. Otherwise you will not get a done signal from this transaction as it will wait for the finished signal from the process that will never come.

Definition at line 723 of file kgpgtransaction.cpp.

KGpgTransaction::ts_boolanswer KGpgTransaction::confirmOverwrite ( KUrl & currentFile )

protectedvirtual

called when GnuPG asks for confirmation for overwriting a file

Parameters

currentFile fill in the current filename for the user dialog

Returns: what to answer to GnuPG

Return values

BA_YES	file will be overwritten, is ignored
BA_NO	file will not be overwritten, if currentFile is given this will automatically be provided as alternative to GnuPG
BA_UNKNOWN	ask the user for a choice or abort, currentFile is provided to the user as a hint about the original filename, if currentFile is empty the transaction is aborted

The default implementation will just return BA_UNKNOWN without setting a filename, causing a sequence error.

Reimplemented in KGpgEncrypt, and KGpgGenerateRevoke.

Definition at line 465 of file kgpgtransaction.cpp.

void KGpgTransaction::done ( int result )

signal

Emitted when the operation was completed.

Parameters

result return status of the transaction

See also: ts_transaction for the common status codes. Each transaction may define additional status codes.

void KGpgTransaction::finish ( )

protectedvirtual

Called when the gpg process finishes.

You may reimplement this member if you need to do some special operations after process completion. The provided one simply does nothing which should be enough for most cases.

Reimplemented in KGpgDelUid, KGpgTextOrFileTransaction, KGpgVerify, KGpgGenerateKey, KGpgKeyserverTransaction, KGpgKeyserverSearchTransaction, and KGpgGenerateRevoke.

Definition at line 484 of file kgpgtransaction.cpp.

const QString & KGpgTransaction::getDescription ( ) const

return description of this transaction

Returns: string used to describe what's going on

This is especially useful when using this transaction from a KJob.

Definition at line 703 of file kgpgtransaction.cpp.

QString KGpgTransaction::getIdHints ( ) const

protected

get string of all userid hints

Returns: concatenation of all ids previously added with addIdHint().

Definition at line 550 of file kgpgtransaction.cpp.

GPGProc * KGpgTransaction::getProcess ( )

protected

get a reference to the gpg process object

Returns: gpg process object

This returns a reference to the gpg process object used internally. In case you need to do some special things (e.g. changing the output mode) you can modify this object.

Usually you will not need this.

Warning: Never free this object!

Definition at line 556 of file kgpgtransaction.cpp.

int KGpgTransaction::getSuccess ( ) const

protected

get the success value that will be returned with the done signal

Definition at line 442 of file kgpgtransaction.cpp.

bool KGpgTransaction::hasInputTransaction ( ) const

check if another transaction will sent input to this

Definition at line 730 of file kgpgtransaction.cpp.

bool KGpgTransaction::hintLine	(	const ts_hintType	hint,
		const QString &	args
	)

protectedvirtual

Called for a set of hint messages.

Parameters

hint	the hint type given by GnuPG
args	the arguments given to the hint

Returns: if the hint was parsed correctly

Return values

true	everything is fine
false	something went wrong (e.g. syntax error)

The default implementation will do nothing but checking for some argument counts. Override this and handle all interesting hints yourself. Don't forget to call the default implementation at the end.

Definition at line 473 of file kgpgtransaction.cpp.

void KGpgTransaction::infoProgress	(	qulonglong	processedAmount,
		qulonglong	totalAmount
	)

signal

emits procentual status information

Parameters

processedAmount	how much of the job is done
totalAmount	how much needs to be done to complete this job

void KGpgTransaction::insertArgument	(	const int	pos,
		const QString &	arg
	)

protected

insert an argument at the given position

Parameters

pos	position to insert at
arg	new argument

Definition at line 593 of file kgpgtransaction.cpp.

void KGpgTransaction::insertArguments	(	const int	pos,
		const QStringList &	args
	)

protected

insert arguments at the given position

Parameters

pos	position to insert at
args	new arguments

Definition at line 599 of file kgpgtransaction.cpp.

void KGpgTransaction::kill ( )

abort this operation as soon as possible

Definition at line 736 of file kgpgtransaction.cpp.

void KGpgTransaction::newPassphraseEntered ( )

protectedvirtual

called when the user entered a new passphrase

This is called after askNewPassphrase() was called, the user has entered a new passphrase and it was sent to the GnuPG process.

The default implementation does nothing.

Reimplemented in KGpgGenerateKey.

Definition at line 742 of file kgpgtransaction.cpp.

virtual bool KGpgTransaction::nextLine ( const QString & line )

protectedpure virtual

Called for every line the gpg process writes.

Parameters

line	the input from the process

Returns: true if "quit" should be sent to process

You need to implement this member to get a usable subclass.

When this function returns true "quit" is written to the process.

Implemented in KGpgExport, KGpgDelUid, KGpgTextOrFileTransaction, KGpgEncrypt, KGpgVerify, KGpgDecrypt, KGpgEditKeyTransaction, KGpgGenerateKey, KGpgDelSign, KGpgSendKeys, KGpgSignUid, KGpgKeyserverSearchTransaction, KGpgKeyserverGetTransaction, KGpgGenerateRevoke, KGpgSignKey, KGpgPrimaryUid, KGpgDelKey, KGpgAddUid, KGpgChangeTrust, KGpgChangeDisable, KGpgChangeExpire, KGpgAddPhoto, and KGpgChangePass.

bool KGpgTransaction::passphraseReceived ( )

protectedvirtual

called when GnuPG accepted the passphrase

Returns: if the input channel to GnuPG should be closed

Return values

true	close the input channel of the GnuPG process
false	keep the GnuPG input channel open

This allows a transaction to handle passphrase success in a special way. The default implementation will just return true.

Reimplemented in KGpgSignUid, KGpgGenerateRevoke, KGpgSignKey, KGpgPrimaryUid, and KGpgChangePass.

Definition at line 518 of file kgpgtransaction.cpp.

bool KGpgTransaction::passphraseRequested ( )

protectedvirtual

called when GnuPG asks for a passphrase

Returns: if the processing should continue

Return values

true	processing should continue
false	an error occurred, transaction should be aborted

This allows a transaction to implement special handling for passphrases, e.g. when both old and new passphrase must be requested when changing it. The default implementation will just call askPassphrase().

Reimplemented in KGpgChangePass.

Definition at line 512 of file kgpgtransaction.cpp.

void KGpgTransaction::postStart ( )

protectedvirtual

Called when the gpg process is up and running.

This functions is connected to the started() signal of the gpg process.

Reimplemented in KGpgGenerateKey.

Definition at line 530 of file kgpgtransaction.cpp.

bool KGpgTransaction::preStart ( )

protectedvirtual

Called before the gpg process is started.

Returns: true if the process should be started

You may reimplement this member if you need to do some special operations before the process is started. The command line of the process may be modified for the last time here.

When you notice that some values passed are invalid or the transaction does not need to be run for some other reason you should call setSuccess() to set the return value and return false. In this case the process is not started but the value is immediately returned.

Reimplemented in KGpgExport, KGpgDelUid, KGpgTextOrFileTransaction, KGpgKeyserverTransaction, KGpgGenerateKey, KGpgUidTransaction, KGpgSendKeys, KGpgKeyserverSearchTransaction, KGpgEditKeyTransaction, KGpgKeyserverGetTransaction, KGpgGenerateRevoke, KGpgDelKey, KGpgChangeTrust, KGpgAddUid, KGpgChangeDisable, and KGpgChangePass.

Definition at line 524 of file kgpgtransaction.cpp.

void KGpgTransaction::replaceArgument	(	const int	pos,
		const QString &	arg
	)

protected

replace the argument at the given position

Parameters

pos	position of old argument
arg	new argument

Definition at line 582 of file kgpgtransaction.cpp.

void KGpgTransaction::setDescription ( const QString & description )

protected

set the description returned in getDescription()

Parameters

description the new description of this transaction

Definition at line 489 of file kgpgtransaction.cpp.

void KGpgTransaction::setGnuPGHome ( const QString & home )

sets the home directory of GnuPG called for this transaction

Definition at line 663 of file kgpgtransaction.cpp.

void KGpgTransaction::setInputTransaction ( KGpgTransaction * ta )

connect the standard input of this transaction to another process

Parameters

proc	process to read data from

Once the input process is connected this transaction will not emit the done signal until the input process sends the done signal.

The basic idea is that when an input transaction is set you only need to care about this transaction. The other transaction is automatically started when this one is started and is destroyed when this one is.

Definition at line 709 of file kgpgtransaction.cpp.

void KGpgTransaction::setSuccess ( const int v )

protected

set the success value that will be returned with the done signal

Parameters

v	the new success value

You should use 0 as success value. Other values can be defined as needed.

Definition at line 448 of file kgpgtransaction.cpp.

void KGpgTransaction::start ( )

Start the operation.

Definition at line 390 of file kgpgtransaction.cpp.

void KGpgTransaction::statusMessage ( const QString & msg )

signal

emits textual status information

Parameters

msg	the status message

void KGpgTransaction::unexpectedLine ( const QString & line )

protected

notify of an unexpected line

This will print out the line to the console to ease debugging.

Definition at line 506 of file kgpgtransaction.cpp.

int KGpgTransaction::waitForFinished ( const int msecs = -1 )

blocks until the transaction is complete

Returns: the result of the transaction like done() would

Return values

TS_USER_ABORTED the timeout expired

If this transaction has another transaction set as input then it would wait for those transaction to finish first. The msecs argument is used as limit for both transactions then so you can end up waiting twice the given time (or longer if you have more transactions chained).

Definition at line 681 of file kgpgtransaction.cpp.

void KGpgTransaction::waitForInputTransaction ( )

protected

wait until the input transaction has finished

Definition at line 495 of file kgpgtransaction.cpp.

void KGpgTransaction::write	(	const QByteArray &	a,
		const bool	lf = `true`
	)

protected

write data to standard input of gpg process

Parameters

a	data to write
lf	if line feed should be appended to message

Use this function to interact with the gpg process. A carriage return is appended to the data automatically. Usually you will call this function from nextLine().

Definition at line 413 of file kgpgtransaction.cpp.

void KGpgTransaction::write ( const int i )

protected

write data to standard input of gpg process

Parameters

i	data to write

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 422 of file kgpgtransaction.cpp.

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

kgpg

Public Types

Signals

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

kgpg

kdeutils API Reference

Search