KAuth 5.109.0
Public Types | Public Member Functions | Static Public Member Functions | List of all members
KAuth::ActionReply

Class that encapsulates a reply coming from the helper after executing an action. More...

#include <KAuth/ActionReply>

Public Types

enum  Error {
  NoError = 0 , NoResponderError , NoSuchActionError , InvalidActionError ,
  AuthorizationDeniedError , UserCancelledError , HelperBusyError , AlreadyStartedError ,
  DBusError , BackendError
}
 The enumeration of the possible values of errorCode() when type() is ActionReply::KAuthError. More...
 
enum  Type { KAuthErrorType , HelperErrorType , SuccessType }
 Enumeration of the different kinds of replies. More...
 

Public Member Functions

 ActionReply ()
 Default constructor. Sets type() to Success and errorCode() to zero.
 
 ActionReply (const ActionReply &reply)
 Copy constructor.
 
 ActionReply (int errorCode)
 Constructor that creates a KAuthError reply with a specified error code.
 
 ActionReply (Type type)
 Constructor to directly set the type.
 
virtual ~ActionReply ()
 Virtual destructor.
 
void addData (const QString &key, const QVariant &value)
 Convenience method to add some data to the reply.
 
QVariantMap data () const
 Returns the custom data coming from the helper.
 
int error () const
 Returns the error code of an error reply.
 
Error errorCode () const
 Returns the error code of an error reply.
 
QString errorDescription () const
 Gets a human-readble description of the error, if available.
 
bool failed () const
 Returns true if type() != Success.
 
bool operator!= (const ActionReply &reply) const
 Negated comparison operator.
 
ActionReplyoperator= (const ActionReply &reply)
 Assignment operator.
 
bool operator== (const ActionReply &reply) const
 Comparison operator.
 
QByteArray serialized () const
 Serialize the reply into a QByteArray.
 
void setData (const QVariantMap &data)
 Sets the custom data to send back to the application.
 
void setError (int error)
 Sets the error code of an error reply.
 
void setErrorCode (Error errorCode)
 Sets the error code of an error reply.
 
void setErrorDescription (const QString &error)
 Sets a human-readble description of the error.
 
void setType (Type type)
 Sets the reply type.
 
bool succeeded () const
 Returns true if type() == Success.
 
Type type () const
 Returns the reply's type.
 

Static Public Member Functions

static const ActionReply AlreadyStartedReply ()
 errorCode() == AlreadyStartedError
 
static const ActionReply AuthorizationDeniedReply ()
 errorCode() == AuthorizationDenied
 
static const ActionReply DBusErrorReply ()
 errorCode() == DBusError
 
static ActionReply deserialize (const QByteArray &data)
 Deserialize a reply from a QByteArray.
 
static const ActionReply HelperBusyReply ()
 errorCode() == HelperBusy
 
static const ActionReply HelperErrorReply ()
 An empty reply with type() == HelperError and errorCode() == -1.
 
static const ActionReply HelperErrorReply (int error)
 An empty reply with type() == HelperError and error is set to the passed value.
 
static const ActionReply InvalidActionReply ()
 errorCode() == InvalidAction
 
static const ActionReply NoResponderReply ()
 errorCode() == NoResponder
 
static const ActionReply NoSuchActionReply ()
 errorCode() == NoSuchAction
 
static const ActionReply SuccessReply ()
 An empty successful reply. Same as using the default constructor.
 
static const ActionReply UserCancelledReply ()
 errorCode() == UserCancelled
 

Detailed Description

Class that encapsulates a reply coming from the helper after executing an action.

Helper applications will return this to describe the result of the action.

Callers should access the reply though the KAuth::ExecuteJob job.

Since
4.4

Member Enumeration Documentation

◆ Error

The enumeration of the possible values of errorCode() when type() is ActionReply::KAuthError.

Enumerator
NoError 

No error.

NoResponderError 

The helper responder object hasn't been set. This shouldn't happen if you use the KAUTH_HELPER macro in the helper source.

NoSuchActionError 

The action you tried to execute doesn't exist.

InvalidActionError 

You tried to execute an invalid action object.

AuthorizationDeniedError 

You don't have the authorization to execute the action.

UserCancelledError 

Action execution has been cancelled by the user.

HelperBusyError 

The helper is busy executing another action (or group of actions). Try later.

AlreadyStartedError 

The action was already started and is currently running.

DBusError 

An error from D-Bus occurred.

BackendError 

The underlying backend reported an error.

◆ Type

Enumeration of the different kinds of replies.

Enumerator
KAuthErrorType 

An error reply generated by the library itself.

HelperErrorType 

An error reply generated by the helper.

SuccessType 

The action has been completed successfully.

Constructor & Destructor Documentation

◆ ActionReply() [1/4]

KAuth::ActionReply::ActionReply ( )

Default constructor. Sets type() to Success and errorCode() to zero.

◆ ActionReply() [2/4]

KAuth::ActionReply::ActionReply ( Type  type)

Constructor to directly set the type.

This constructor directly sets the reply type. You shouldn't need to directly call this constructor, because you can use the more convenient predefined replies constants. You also shouldn't create a reply with the KAuthError type because it's reserved for errors coming from the library.

Parameters
typeThe type of the new reply

◆ ActionReply() [3/4]

KAuth::ActionReply::ActionReply ( int  errorCode)

Constructor that creates a KAuthError reply with a specified error code.

Do not use outside the library.

This constructor is for internal use only, since it creates a reply with KAuthError type, which is reserved for errors coming from the library.

Parameters
errorCodeThe error code of the new reply

◆ ActionReply() [4/4]

KAuth::ActionReply::ActionReply ( const ActionReply reply)

Copy constructor.

◆ ~ActionReply()

virtual KAuth::ActionReply::~ActionReply ( )
virtual

Virtual destructor.

Member Function Documentation

◆ addData()

void KAuth::ActionReply::addData ( const QString &  key,
const QVariant &  value 
)

Convenience method to add some data to the reply.

This method adds the pair key/value to the QVariantMap used to report back custom data to the application.

Use this method if you don't want to create a new QVariantMap only to add a new entry.

Parameters
keyThe new entry's key
valueThe value of the new entry

◆ AlreadyStartedReply()

static const ActionReply KAuth::ActionReply::AlreadyStartedReply ( )
static

errorCode() == AlreadyStartedError

◆ AuthorizationDeniedReply()

static const ActionReply KAuth::ActionReply::AuthorizationDeniedReply ( )
static

errorCode() == AuthorizationDenied

◆ data()

QVariantMap KAuth::ActionReply::data ( ) const

Returns the custom data coming from the helper.

This method is used to get the object that contains the custom data coming from the helper. In the helper's code, you can set it using setData() or the convenience method addData().

Returns
The data coming from (or that will be sent by) the helper

◆ DBusErrorReply()

static const ActionReply KAuth::ActionReply::DBusErrorReply ( )
static

errorCode() == DBusError

◆ deserialize()

static ActionReply KAuth::ActionReply::deserialize ( const QByteArray &  data)
static

Deserialize a reply from a QByteArray.

This method returns a reply from a QByteArray obtained from the serialized() method.

Parameters
dataA QByteArray obtained with serialized()

◆ error()

int KAuth::ActionReply::error ( ) const

Returns the error code of an error reply.

The error code returned is one of the values in the ActionReply::Error enumeration if type() == KAuthError, or is totally application-dependent if type() == HelperError. It also should be zero for successful replies.

Returns
The reply error code

◆ errorCode()

Error KAuth::ActionReply::errorCode ( ) const

Returns the error code of an error reply.

The error code returned is one of the values in the ActionReply::Error enumeration if type() == KAuthError. Result is only valid if the type() == HelperError

Returns
The reply error code

◆ errorDescription()

QString KAuth::ActionReply::errorDescription ( ) const

Gets a human-readble description of the error, if available.

Currently, replies of type KAuthError rarely report an error description. This situation could change in the future.

By now, you can use this method for custom errors of type HelperError.

Returns
The error human-readable description

◆ failed()

bool KAuth::ActionReply::failed ( ) const

Returns true if type() != Success.

◆ HelperBusyReply()

static const ActionReply KAuth::ActionReply::HelperBusyReply ( )
static

errorCode() == HelperBusy

◆ HelperErrorReply() [1/2]

static const ActionReply KAuth::ActionReply::HelperErrorReply ( )
static

An empty reply with type() == HelperError and errorCode() == -1.

◆ HelperErrorReply() [2/2]

static const ActionReply KAuth::ActionReply::HelperErrorReply ( int  error)
static

An empty reply with type() == HelperError and error is set to the passed value.

◆ InvalidActionReply()

static const ActionReply KAuth::ActionReply::InvalidActionReply ( )
static

errorCode() == InvalidAction

◆ NoResponderReply()

static const ActionReply KAuth::ActionReply::NoResponderReply ( )
static

errorCode() == NoResponder

◆ NoSuchActionReply()

static const ActionReply KAuth::ActionReply::NoSuchActionReply ( )
static

errorCode() == NoSuchAction

◆ operator!=()

bool KAuth::ActionReply::operator!= ( const ActionReply reply) const

Negated comparison operator.

See the operator==() for an important notice.

◆ operator=()

ActionReply & KAuth::ActionReply::operator= ( const ActionReply reply)

Assignment operator.

◆ operator==()

bool KAuth::ActionReply::operator== ( const ActionReply reply) const

Comparison operator.

This operator checks if the type and the error code of two replies are the same. It doesn't compare the data or the error descriptions, so be careful.

The suggested use is to compare a reply against one of the predefined error replies:

// Do something...
}
static const ActionReply HelperBusyReply()
errorCode() == HelperBusy

Note that you can do it also by compare errorCode() with the relative enumeration value.

◆ serialized()

QByteArray KAuth::ActionReply::serialized ( ) const

Serialize the reply into a QByteArray.

This is a convenience method used internally to sent the reply to a remote peer. To recreate the reply, use deserialize()

Returns
A QByteArray representation of this reply

◆ setData()

void KAuth::ActionReply::setData ( const QVariantMap &  data)

Sets the custom data to send back to the application.

In the helper's code you can use this function to set an QVariantMap with custom data that will be sent back to the application.

Parameters
dataThe new QVariantMap object.

◆ setError()

void KAuth::ActionReply::setError ( int  error)

Sets the error code of an error reply.

If you're setting the error code in the helper because you need to return an error to the application, please make sure you already have set the type to HelperError, either by calling setType() or by creating the reply in the right way.

If the type is Success when you call this method, it will become KAuthError

Parameters
errorThe new reply error code

◆ setErrorCode()

void KAuth::ActionReply::setErrorCode ( Error  errorCode)

Sets the error code of an error reply.

See also
If you're setting the error code in the helper, use setError(int)

If the type is Success when you call this method, it will become KAuthError

Parameters
errorCodeThe new reply error code

◆ setErrorDescription()

void KAuth::ActionReply::setErrorDescription ( const QString &  error)

Sets a human-readble description of the error.

Call this method from the helper if you want to send back a description for a custom error. Note that this method doesn't affect the errorCode in any way

Parameters
errorThe new error description

◆ setType()

void KAuth::ActionReply::setType ( Type  type)

Sets the reply type.

Every time you create an action reply, you implicitly set a type. Default constructed replies or ActionReply::SuccessReply have type() == Success. ActionReply::HelperErrorReply has type() == HelperError. Predefined error replies have type() == KAuthError.

This means you rarely need to change the type after the creation, but if you need to, don't set it to KAuthError, because it's reserved for errors coming from the library.

Parameters
typeThe new reply type

◆ succeeded()

bool KAuth::ActionReply::succeeded ( ) const

Returns true if type() == Success.

◆ SuccessReply()

static const ActionReply KAuth::ActionReply::SuccessReply ( )
static

An empty successful reply. Same as using the default constructor.

◆ type()

Type KAuth::ActionReply::type ( ) const

Returns the reply's type.

◆ UserCancelledReply()

static const ActionReply KAuth::ActionReply::UserCancelledReply ( )
static

errorCode() == UserCancelled