Methods
| GetCaptchas | () | → | a(ussuas): Captcha_Info, u: Number_Required, s: Language | |
| GetCaptchaData | (u: ID, s: Mime_Type) | → | ay: Captcha_Data | |
| AnswerCaptchas | (a{us}: Answers) | → | nothing | |
| CancelCaptcha | (u: Reason, s: Debug_Message) | → | nothing |
Properties
| CanRetryCaptcha | b | Read only | Immutable | |
| CaptchaStatus | u (Captcha_Status) | Read only | ||
| CaptchaError | s (DBus_Error_Name) | Read only | ||
| CaptchaErrorDetails | a{sv} (String_Variant_Map) | Read only |
Types
| Captcha_Cancel_Reason | Enum | u | |
| Captcha_Status | Enum | u | |
| Captcha_Flags | Flags | u | |
| Captcha_Answers | Mapping | a{us} | |
| Captcha_Info | Struct | (ussuas) |
Description
A channel interface for captcha authentication. When this interface appears on a ServerAuthentication channel, it represents authentication with the server. In future, it could also be used to authenticate with secondary services, or even to authenticate end-to-end connections with contacts. As a result, this interface does not REQUIRE ServerAuthentication to allow for a potential future Channel.Type.PeerAuthentication interface.
In any protocol that requires a captcha, the connection manager can use this channel to let a user interface carry out a simple captcha handshake with it, as a way to test the user is human interactively.
For channels managed by a ChannelDispatcher, only the channel's Handler may call the methods on this interface. Other clients MAY observe the authentication process by watching its signals and properties.
The most commonly used form of captcha challenge is OCR (recognition of distorted letters or words in an image), but for accessibility reasons, this interface also allows various other types of challenge, such as plain-text questions or recognition of words in audio. Its structure is modelled on XMPP's XEP-0158, but can be used with other protocols by mapping their semantics into those used in XMPP.
Rationale:
It is important to support multiple types of captcha challenge to avoid discriminating against certain users; for instance, blind or partially-sighted users cannot be expected to answer an OCR challenge.
XEP-0158 supports a superset of all other known protocols' captcha interfaces, and is sufficiently elaborate that we expect it will continue to do so.
There can only be one Handler, which is a good fit for the question/answer model implied by captchas.
Methods
GetCaptchas () → a(ussuas): Captcha_Info, u: Number_Required, s: Language
Returns
- Captcha_Info — a(ussuas) (Captcha_Info_List)
- Number_Required — u
- Language — s (Language_Tag)
Gets information regarding each of the captcha methods available and which and how many need to be successfully answered
To call this method successfully, the state must be Local_Pending or Try_Again. If it is Local_Pending, it remains Local_Pending. If called more than once while in Local_Pending state, or if the state is Try_Again, this method fetches a new set of captcha challenges, if possible, and the state returns to Local_Pending.
Rationale:
For instance, you could call GetCaptchas again from Local_Pending state if the user indicates that they can't understand the initially-offered captcha.
This is a method, not a property, so that it can be used to fetch more than one set of captcha challenges, and so that change notification is not required. Only the Handler should call this method and calling GetAll would not reduce round-trips, so the usual reasons to prefer a property do not apply here.
Possible Errors
- Not Available
- Network Error
GetCaptchaData (u: ID, s: Mime_Type) → ay: Captcha_Data
Parameters
- ID — u
- Mime_Type — s
Rationale:
Returns
- Captcha_Data — ay
Fetch and return the captcha data. In protocols where captchas are downloaded out-of-band (for instance via HTTP), the connection manager is expected to do so.
Returns an empty array if the type was "qa"
Rationale:
If audio-based and image-based captchas are both available, we don't want to waste time downloading the audio until/unless the user asks to hear it. The extra D-Bus round-trips are not a problem, since they are expected to be quick compared with the time taken for the user to solve the captcha.
Possible Errors
- Not Available
- Network Error
AnswerCaptchas (a{us}: Answers) → nothing
Parameters
- Answers — a{us} (Captcha_Answers)
Answer as many captchas as desired and/or required.
Callable in state Local_Pending only. State changes to Remote_Pending.
Possible Errors
- Not Available
- Network Error
CancelCaptcha (u: Reason, s: Debug_Message) → nothing
Parameters
- Reason — u (Captcha_Cancel_Reason)
- Debug_Message — s
Cancel. State changes to Failed with error NotAvailable or Cancelled if it isn't already Failed. All you can do now is to close the channel.
Possible Errors
- Not Available
Properties
CanRetryCaptcha — b
If true, GetCaptchas can be expected to return new captcha information when in the Local_Pending state. If false, GetCaptchas will return NotAvailable on subsequent calls.
Rationale:
Refreshing the captcha isn't required to work, although some protocols and implementations allow it. This is usually done in case a given captcha is unintelligible.
CaptchaStatus — u (Captcha_Status)
org.freedesktop.DBus.Properties.PropertiesChanged
signal is emitted with the new value.
The current status of this channel.
Because only the Handler should call methods on this interface, the Handler MAY reduce round-trips by not fetching the initial value of this property, and instead assume that is initially Local_Pending.
Rationale:
This assumption normally avoids the need to call GetAll(), since the values of CaptchaError and CaptchaErrorDetails are also implied by this assumption, and the only other property is CanRetryCaptcha, which is immutable.
CaptchaError — s (DBus_Error_Name)
org.freedesktop.DBus.Properties.PropertiesChanged
signal is emitted with the new value.
The reason for the CaptchaStatus, or an empty string if the state is neither Try_Again nor Failed.
Typical values: "", Cancelled, AuthenticationFailed, CaptchaNotSupported
In particular, an ordinary authentication failure (as would be produced for an incorrect answer) SHOULD be represented by AuthenticationFailed, cancellation by the user's request SHOULD be represented by Cancelled, cancellation due to the inability to display the captcha to the user or otherwise answer it SHOULD be represented by CaptchaNotSupported, and cancellation by a local process due to inconsistent or invalid challenges from the server SHOULD be represented by ServiceConfused.
If this interface appears on a ServerAuthentication channel, and connection to the server fails with an authentication failure, this error code SHOULD be copied into the Connection.ConnectionError signal.
CaptchaErrorDetails — a{sv} (String_Variant_Map)
org.freedesktop.DBus.Properties.PropertiesChanged
signal is emitted with the new value.
If CaptchaError is non-empty, any additional information about the last disconnection; otherwise, the empty map. The keys and values are the same as for the second argument of Connection.ConnectionError.
If this interface appears on a ServerAuthentication channel, and connection to the server fails with an authentication failure, these details SHOULD be copied into the Connection.ConnectionError signal.
Types
Captcha_Cancel_Reason — u
A reason why captcha authentication was aborted by the client.
- User_Cancelled (0)
- Not_Supported (1)
- Service_Confused (2)
Rationale:
Captcha_Status — u
- Local_Pending (0)
- Remote_Pending (1)
- Succeeded (2)
- Try_Again (3)
- Failed (4)
Captcha_Flags — u
Extra flags to include with Captcha information
- Required (1)
Captcha_Answers — a{us}
- ID — u
- Answer — s
Captcha_Info — (ussuas)
A struct containing information regarding a single captcha mechanism.
- ID — u
- Type — s
- Label — s
- Flags — u (Captcha_Flags)
- Available_MIME_Types — as
The ID with which to reference this captcha method when retrieving its data and answering it. They are unique within this channel instance only.
The type of challenge
as defined by XEP-0158. For instance, the commonly-used
"type the letters/words you see in this image" challenge is
represented by ocr
A human-readable label for the challenge, as defined in XEP-0158.
If the server does not supply a label for a challenge of type
other than qa, connection managers SHOULD set Label
to an empty string instead of generating their own text.
If the Label is an empty string, the Handler SHOULD replace
it with a generic label in the user's locale, such as
the strings suggested in XEP-0158 (for instance,
Enter the text you see for ocr
challenges). The Handler MAY use those generic labels
in any case, as per
the
Internationalization Considerations section of XEP-0158.
Rationale:
Connection managers are not usually localized, so text generated by the connection manager would be in English, regardless of the user's locale. The Handler is better-placed to generate a generic Label in the user's locale.
For challenges of type qa, the Label is a plain-text
question for the user to answer. The connection manager
SHOULD NOT provide an empty Label; if it does, the Handler
SHOULD treat that challenge as impossible, and SHOULD NOT
attempt to display it.
One flag defined: Required. Most captchas will have no flags.
A list of MIME types the server is offering to provide for this captcha method.