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

Public Types | Public Slots | Signals | Public Member Functions
Tp::CaptchaAuthentication Class Reference
Channel proxies

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

`#include <TelepathyQt/CaptchaAuthentication>`

Inherits Tp::Object.

List of all members.

## 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)

## 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)

## 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