Home · Modules · All Classes · All Namespaces
Public Types | Public Slots | Signals | Public Member Functions | List of all members
Tp::CaptchaAuthentication Class Reference

The CaptchaAuthentication class exposes CaptchaAuthentication's features for channels implementing it. More...

#include <TelepathyQt/CaptchaAuthentication>

Inherits Tp::Object.

Public Types

enum  ChallengeType {
  NoChallenge, OCRChallenge, AudioRecognitionChallenge, PictureQuestionChallenge,
  PictureRecognitionChallenge, TextQuestionChallenge, SpeechQuestionChallenge, SpeechRecognitionChallenge,
  VideoQuestionChallenge, VideoRecognitionChallenge, UnknownChallenge
}
 

Public Slots

Tp::PendingOperationcancel (Tp::CaptchaCancelReason reason, const QString &message=QString())
 

Signals

void statusChanged (Tp::CaptchaStatus status)
 
- Signals inherited from Tp::Object
void propertyChanged (const QString &propertyName)
 

Public Member Functions

virtual ~CaptchaAuthentication ()
 
ChannelPtr channel () const
 
bool canRetry () const
 
Tp::CaptchaStatus status () const
 
QString error () const
 
Connection::ErrorDetails errorDetails () const
 
Tp::PendingCaptchasrequestCaptchas (const QStringList &preferredMimeTypes=QStringList(), ChallengeTypes preferredTypes=~ChallengeTypes(NoChallenge))
 
Tp::PendingOperationanswer (uint id, const QString &answer)
 
Tp::PendingOperationanswer (const Tp::CaptchaAnswers &response)
 
- Public Member Functions inherited from Tp::Object
virtual ~Object ()
 
- Public Member Functions inherited from Tp::RefCounted
 RefCounted ()
 
virtual ~RefCounted ()
 

Additional Inherited Members

- Protected Member Functions inherited from Tp::Object
 Object ()
 
void notify (const char *propertyName)
 

Detailed Description

The CaptchaAuthentication class exposes CaptchaAuthentication's features for channels implementing it.

A ServerAuthentication channel can implement a CaptchaAuthentication interface: this class exposes all the features this interface provides in a high-level fashion. It is a mechanism for retrieving a captcha challenge from a connection manager and answering it.

This class is meant to be used just during authentication phase. It is useful just for platform-level handlers which are meant to handle authentication - if you are implementing a client which is meant to live in a Telepathy-aware platform, you probably won't need to handle this unless you have very special needs.

Note that CaptchaAuthentication cannot be instantiated directly, instead the accessor method from ServerAuthenticationChannel (ServerAuthenticationChannel::captchaAuthentication) should be used.

See Asynchronous Object Model, Shared Pointer Usage

Member Enumeration Documentation

◆ ChallengeType

Enumerator
NoChallenge 
OCRChallenge 
AudioRecognitionChallenge 
PictureQuestionChallenge 
PictureRecognitionChallenge 
TextQuestionChallenge 
SpeechQuestionChallenge 
SpeechRecognitionChallenge 
VideoQuestionChallenge 
VideoRecognitionChallenge 
UnknownChallenge 

Constructor & Destructor Documentation

◆ ~CaptchaAuthentication()

Tp::CaptchaAuthentication::~CaptchaAuthentication ( )
virtual

Class destructor.

Member Function Documentation

◆ channel()

Tp::ChannelPtr Tp::CaptchaAuthentication::channel ( ) const

Return the channel associated with this captcha.

CaptchaAuthentication is just a representation of an interface which can be implemented by a ServerAuthentication channel. This function will return the channel implementing the interface represented by this instance.

Note that it is currently guaranteed the ChannelPtr returned by this function will be a ServerAuthenticationChannel.

Returns
The channel implementing the CaptchaAuthentication interface represented by this instance.

◆ canRetry()

bool Tp::CaptchaAuthentication::canRetry ( ) const

Return whether this channel supports updating its captchas or not.

Some protocols allow their captchas to be reloaded providing new data to the user; for example, in case the image provided is not easily readable. This function checks if this instance supports such a feature.

Note that in case this function returns true, requestCaptchas can be called safely after a failed answer attempt.

Returns
true if a new captcha can be fetched from this channel, false otherwise.

◆ status()

Tp::CaptchaStatus Tp::CaptchaAuthentication::status ( ) const

Return the current status of the captcha.

Returns
The current status of the captcha.

◆ error()

QString Tp::CaptchaAuthentication::error ( ) const

Return the code of the last error happened on the interface.

Returns
An error code describing the last error occurred.
See also
errorDetails

◆ errorDetails()

Connection::ErrorDetails Tp::CaptchaAuthentication::errorDetails ( ) const

Return the details of the last error happened on the interface.

Returns
Further details describing the last error occurred.
See also
error

◆ requestCaptchas()

PendingCaptchas * Tp::CaptchaAuthentication::requestCaptchas ( const QStringList &  preferredMimeTypes = QStringList(),
ChallengeTypes  preferredTypes = ~ChallengeTypes(NoChallenge) 
)

Request captcha challenges from the connection manager.

Even if most protocols usually provide a single captcha challenge (OCR), for a variety of reasons some of them could provide a number of different challenge types, requiring one or more of them to be answered.

This method initiates a request to the connection manager for obtaining the most compatible captcha challenges available. It allows to supply a number of supported mimetypes and types, so that the request will fail if the CM is unable to provide a challenge compatible with what the handler supports, or will provide the best one available otherwise.

Please note that all the challenges returned by this request must be answered in order for the authentication to succeed.

Note that if the CM supports retrying the captcha, this function can also be used to load a new set of captchas. In general, if canRetry returns true, one can expect this function to always return a different set of challenges which invalidates any other obtained previously.

Parameters
preferredMimeTypesA list of mimetypes supported by the handler, or an empty list if every mimetype can be supported.
preferredTypesA list of challenge types supported by the handler.
Returns
A PendingCaptchas which will emit PendingCaptchas::finished when the request has been completed and all the payloads have been downloaded.
See also
canRetry
cancel
answer

◆ answer() [1/2]

Tp::PendingOperation * Tp::CaptchaAuthentication::answer ( uint  id,
const QString &  response 
)

Overloaded function. Convenience method when just a single captcha requires to be answered.

Note that you need to answer only the last set of challenges returned, in case requestCaptchas was invoked multiple times.

Please note that if this operation succeeds, the channel will be closed right after.

Parameters
idThe id of the challenge being answered.
responseThe answer of this challenge.
Returns
A PendingOperation which will emit PendingOperation::finished upon the outcome of the answer procedure. Upon success, the operation will complete once the channel is closed.
See also
requestCaptchas
answer

◆ answer() [2/2]

Tp::PendingOperation * Tp::CaptchaAuthentication::answer ( const Tp::CaptchaAnswers response)

Answer a set of challenges.

Challenges obtained with requestCaptchas should be answered using this method. Note that every challenge returned by the last invocation of requestCaptchas must be answered in order for the operation to succeed.

Usually, most protocols will require just a single challenge to be answered: if that is the case, you can use the convenience overload.

Note that you need to answer only the last set of challenges returned, in case requestCaptchas was invoked multiple times.

Please note that if this operation succeeds, the channel will be closed right after.

Parameters
responseA set of answers mapped by their id to the challenges obtained previously
Returns
A PendingOperation which will emit PendingOperation::finished upon the outcome of the answer procedure. Upon success, the operation will complete once the channel is closed.
See also
requestCaptchas
answer

◆ statusChanged

void Tp::CaptchaAuthentication::statusChanged ( Tp::CaptchaStatus  status)
signal

Emitted when the value of status() changes.

See also
status The new status of this CaptchaAuthentication.

◆ cancel

Tp::PendingOperation * Tp::CaptchaAuthentication::cancel ( Tp::CaptchaCancelReason  reason,
const QString &  message = QString() 
)
slot

Cancel the current challenge.

Please note that if this operation succeeds, the channel will be closed right after.

Note that this function has not the same semantics as retry. The status of the CaptchaAuthentication will change to Failed even if the channel supports retrying. This function should be called only if the user refuses to answer any challenge. Instead, if the user wishes to retry, you should just call requestCaptchas one more time.

Parameters
reasonThe reason why the challenge has been cancelled.
messageA message detailing the cancel reason.
Returns
A PendingOperation which will emit PendingOperation::finished upon the outcome of the cancel procedure. Upon success, the operation will complete once the channel is closed.
See also
requestCaptchas