The CaptchaAuthentication class exposes CaptchaAuthentication's features for channels implementing it. More...
#include <TelepathyQt/CaptchaAuthentication>
Inherits Tp::Object.
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.
Member Enumeration Documentation
◆ ChallengeType
Constructor & Destructor Documentation
◆ ~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
trueif a new captcha can be fetched from this channel,falseotherwise.
◆ 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
-
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.
◆ 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
-
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
◆ 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
-
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
◆ statusChanged
|
signal |
Emitted when the value of status() changes.
- See also
- status The new status of this CaptchaAuthentication.
◆ cancel
|
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
