Tp::CaptchaAuthentication Class Reference

| Home · All Classes · All Namespaces · Modules · Functions · Files

Public Types | Public Slots | Signals | Public Member Functions | List of all members
Tp::CaptchaAuthentication Class Reference
Channel proxies

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::PendingOperation * | cancel (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::PendingCaptchas * | requestCaptchas (const QStringList &preferredMimeTypes=QStringList(), ChallengeTypes preferredTypes=~ChallengeTypes(NoChallenge))
Tp::PendingOperation * | answer (uint id, const QString &answer)
Tp::PendingOperation * | answer (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

enum Tp::CaptchaAuthentication::ChallengeType

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

## Constructor & Destructor Documentation

Tp::CaptchaAuthentication::~CaptchaAuthentication | ( |  | ) |
| virtual

Class destructor.

## Member Function Documentation

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.

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.

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

Return the current status of the captcha.

Returns
  The current status of the captcha.

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

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

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

  preferredMimeTypes | A list of mimetypes supported by the handler, or an empty list if every mimetype can be supported.
  preferredTypes | A 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

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

  id | The id of the challenge being answered.
  response | The 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

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

  response | A 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

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

Emitted when the value of status() changes.

See Also
  status The new status of this CaptchaAuthentication.

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

  reason | The reason why the challenge has been cancelled.
  message | A 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