Tp::PendingOperation Class Reference

The PendingOperation class is a base class for pending asynchronous operations. More...

#include <TelepathyQt/PendingOperation>

Inherits QObject.

Inherited by Tp::Farstream::PendingChannel, Tp::PendingAccount, Tp::PendingCallContent, Tp::PendingCaptchas, Tp::PendingChannel, Tp::PendingChannelRequest, Tp::PendingComposite, Tp::PendingConnection, Tp::PendingContactAttributes, Tp::PendingContactInfo, Tp::PendingContacts, Tp::PendingDBusTubeConnection, Tp::PendingDebugMessageList, Tp::PendingFailure, Tp::PendingHandles, Tp::PendingReady, Tp::PendingSendMessage, Tp::PendingStreamedMediaStreams, Tp::PendingStreamTubeConnection, Tp::PendingString, Tp::PendingStringList, Tp::PendingSuccess, Tp::PendingVariant, Tp::PendingVariantMap, and Tp::PendingVoid.

Signals
void	finished (Tp::PendingOperation *operation)

Public Member Functions
virtual	~PendingOperation ()
bool	isFinished () const
bool	isValid () const
bool	isError () const
QString	errorName () const
QString	errorMessage () const

Protected Slots
void	setFinished ()
void	setFinishedWithError (const QString &name, const QString &message)
void	setFinishedWithError (const QDBusError &error)

Protected Member Functions
	PendingOperation (const SharedPtr< RefCounted > &object)
SharedPtr< RefCounted >	object () const

Detailed Description

The PendingOperation class is a base class for pending asynchronous operations.

This class represents an incomplete asynchronous operation, such as a D-Bus method call. When the operation has finished, it emits finished(). The slot or slots connected to the finished() signal may obtain additional information from the pending operation.

In simple cases, like a D-Bus method with no 'out' arguments or for which all 'out' arguments are to be ignored (so the possible results are success with no extra information, or failure with an error code), the trivial subclass PendingVoid can be used.

For pending operations that produce a result, another subclass of PendingOperation can be used, with additional methods that provide that result to the library user.

After finished() is emitted, the PendingOperation is automatically deleted using deleteLater(), so library users must not explicitly delete this object.

The design is loosely based on KDE's KJob.

See Asynchronous Object Model

Constructor & Destructor Documentation

~PendingOperation()

Tp::PendingOperation::~PendingOperation ( )

virtual

Class destructor.

PendingOperation()

Tp::PendingOperation::PendingOperation ( const SharedPtr< RefCounted > &  object )

protected

Construct a new PendingOperation object.

Parameters

object

The object on which this pending operation takes place.

Member Function Documentation

isFinished()

bool Tp::PendingOperation::isFinished

(

)

const

Return whether or not the request has finished processing.

The signal finished() is emitted when this changes from false to true.

Equivalent to (isValid() || isError()).

Returns

true if the request has finished, false otherwise.

See also

finished()

isValid()

bool Tp::PendingOperation::isValid

(

)

const

Return whether or not the request completed successfully. If the request has not yet finished processing (isFinished() returns false), this cannot yet be known, and false will be returned.

Equivalent to (isFinished() && !isError()).

Returns

true if the request has finished processing and has completed successfully, false otherwise.

isError()

bool Tp::PendingOperation::isError

(

)

const

Return whether or not the request resulted in an error.

If the request has not yet finished processing (isFinished() returns false), this cannot yet be known, and false will be returned.

Equivalent to (isFinished() && !isValid()).

Returns

true if the request has finished processing and has resulted in an error, false otherwise.

errorName()

QString Tp::PendingOperation::errorName

(

)

const

If isError() returns true, returns the D-Bus error with which the operation failed. If the operation succeeded or has not yet finished, returns an empty string.

Returns

A D-Bus error name, or an empty string.

errorMessage()

QString Tp::PendingOperation::errorMessage

(

)

const

If isError() would return true, returns a debugging message associated with the error, which may be an empty string. Otherwise, return an empty string.

Returns

A debugging message, or an empty string.

finished

void Tp::PendingOperation::finished ( Tp::PendingOperation *  operation )

signal

Emitted when the pending operation finishes, i.e. when isFinished() changes from false to true.

Parameters

operation

This operation object, from which further information may be obtained.

object()

SharedPtr< RefCounted > Tp::PendingOperation::object ( ) const

protected

Return the object on which this pending operation takes place.

Returns

A pointer to a RefCounted object.

setFinished

void Tp::PendingOperation::setFinished ( )

protectedslot

Record that this pending operation has finished successfully, and emit the finished() signal next time the event loop runs.

setFinishedWithError [1/2]

void Tp::PendingOperation::setFinishedWithError ( const QString &  name, const QString &  message  )

protectedslot

Record that this pending operation has finished with an error, and emit the finished() signal next time the event loop runs.

Parameters

name	The D-Bus error name, which must be non-empty.
message	The debugging message.

setFinishedWithError [2/2]

void Tp::PendingOperation::setFinishedWithError ( const QDBusError &  error )

protectedslot

Record that this pending operation has finished with an error, and emit the finished() signal next time the event loop runs.

Parameters

error

The error.

See also

finished()