diff options
Diffstat (limited to 'lib/csapi/registration.h')
| -rw-r--r-- | lib/csapi/registration.h | 849 |
1 files changed, 439 insertions, 410 deletions
diff --git a/lib/csapi/registration.h b/lib/csapi/registration.h index 9002b5c8..21d7f9d7 100644 --- a/lib/csapi/registration.h +++ b/lib/csapi/registration.h @@ -4,427 +4,456 @@ #pragma once -#include "jobs/basejob.h" - -#include "csapi/../identity/definitions/sid.h" -#include "converters.h" #include "csapi/definitions/auth_data.h" +#include "csapi/definitions/request_email_validation.h" +#include "csapi/definitions/request_msisdn_validation.h" +#include "csapi/definitions/request_token_response.h" -namespace QMatrixClient -{ - // Operations +#include "jobs/basejob.h" - /// Register for an account on this homeserver. +namespace Quotient { + +/*! \brief Register for an account on this homeserver. + * + * This API endpoint uses the [User-Interactive Authentication + * API](/client-server-api/#user-interactive-authentication-api), except in the + * cases where a guest account is being registered. + * + * Register for an account on this homeserver. + * + * There are two kinds of user account: + * + * - `user` accounts. These accounts may use the full API described in this + * specification. + * + * - `guest` accounts. These accounts may have limited permissions and may not + * be supported by all servers. + * + * If registration is successful, this endpoint will issue an access token + * the client can use to authorize itself in subsequent requests. + * + * If the client does not supply a `device_id`, the server must + * auto-generate one. + * + * The server SHOULD register an account with a User ID based on the + * `username` provided, if any. Note that the grammar of Matrix User ID + * localparts is restricted, so the server MUST either map the provided + * `username` onto a `user_id` in a logical manner, or reject + * `username`\s which do not comply to the grammar, with + * `M_INVALID_USERNAME`. + * + * Matrix clients MUST NOT assume that localpart of the registered + * `user_id` matches the provided `username`. + * + * The returned access token must be associated with the `device_id` + * supplied by the client or generated by the server. The server may + * invalidate any access token previously associated with that device. See + * [Relationship between access tokens and + * devices](/client-server-api/#relationship-between-access-tokens-and-devices). + * + * When registering a guest account, all parameters in the request body + * with the exception of `initial_device_display_name` MUST BE ignored + * by the server. The server MUST pick a `device_id` for the account + * regardless of input. + * + * Any user ID returned by this API must conform to the grammar given in the + * [Matrix specification](/appendices/#user-identifiers). + */ +class QUOTIENT_API RegisterJob : public BaseJob { +public: + /*! \brief Register for an account on this homeserver. + * + * \param kind + * The kind of account to register. Defaults to `user`. + * + * \param auth + * Additional authentication information for the + * user-interactive authentication API. Note that this + * information is *not* used to define how the registered user + * should be authenticated, but is instead used to + * authenticate the `register` call itself. + * + * \param username + * The basis for the localpart of the desired Matrix ID. If omitted, + * the homeserver MUST generate a Matrix ID local part. + * + * \param password + * The desired password for the account. + * + * \param deviceId + * ID of the client device. If this does not correspond to a + * known client device, a new device will be created. The server + * will auto-generate a device_id if this is not specified. + * + * \param initialDeviceDisplayName + * A display name to assign to the newly-created device. Ignored + * if `device_id` corresponds to a known device. + * + * \param inhibitLogin + * If true, an `access_token` and `device_id` should not be + * returned from this call, therefore preventing an automatic + * login. Defaults to false. + * + * \param refreshToken + * If true, the client supports refresh tokens. + */ + explicit RegisterJob(const QString& kind = QStringLiteral("user"), + const Omittable<AuthenticationData>& auth = none, + const QString& username = {}, + const QString& password = {}, + const QString& deviceId = {}, + const QString& initialDeviceDisplayName = {}, + Omittable<bool> inhibitLogin = none, + Omittable<bool> refreshToken = none); + + // Result properties + + /// The fully-qualified Matrix user ID (MXID) that has been registered. /// - /// This API endpoint uses the `User-Interactive Authentication API`_. - /// - /// Register for an account on this homeserver. - /// - /// There are two kinds of user account: - /// - /// - `user` accounts. These accounts may use the full API described in this specification. - /// - /// - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers. - /// - /// If registration is successful, this endpoint will issue an access token - /// the client can use to authorize itself in subsequent requests. - /// - /// If the client does not supply a ``device_id``, the server must - /// auto-generate one. - /// - /// The server SHOULD register an account with a User ID based on the - /// ``username`` provided, if any. Note that the grammar of Matrix User ID - /// localparts is restricted, so the server MUST either map the provided - /// ``username`` onto a ``user_id`` in a logical manner, or reject - /// ``username``\s which do not comply to the grammar, with - /// ``M_INVALID_USERNAME``. - /// - /// Matrix clients MUST NOT assume that localpart of the registered - /// ``user_id`` matches the provided ``username``. - /// - /// The returned access token must be associated with the ``device_id`` - /// supplied by the client or generated by the server. The server may - /// invalidate any access token previously associated with that device. See - /// `Relationship between access tokens and devices`_. - class RegisterJob : public BaseJob + /// Any user ID returned by this API must conform to the grammar given in + /// the [Matrix specification](/appendices/#user-identifiers). + QString userId() const { return loadFromJson<QString>("user_id"_ls); } + + /// An access token for the account. + /// This access token can then be used to authorize other requests. + /// Required if the `inhibit_login` option is false. + QString accessToken() const { - public: - /*! Register for an account on this homeserver. - * \param kind - * The kind of account to register. Defaults to `user`. - * \param auth - * Additional authentication information for the - * user-interactive authentication API. Note that this - * information is *not* used to define how the registered user - * should be authenticated, but is instead used to - * authenticate the ``register`` call itself. It should be - * left empty, or omitted, unless an earlier call returned an - * response with status code 401. - * \param bindEmail - * If true, the server binds the email used for authentication to - * the Matrix ID with the identity server. - * \param username - * The basis for the localpart of the desired Matrix ID. If omitted, - * the homeserver MUST generate a Matrix ID local part. - * \param password - * The desired password for the account. - * \param deviceId - * ID of the client device. If this does not correspond to a - * known client device, a new device will be created. The server - * will auto-generate a device_id if this is not specified. - * \param initialDeviceDisplayName - * A display name to assign to the newly-created device. Ignored - * if ``device_id`` corresponds to a known device. - * \param inhibitLogin - * If true, an ``access_token`` and ``device_id`` should not be - * returned from this call, therefore preventing an automatic - * login. Defaults to false. - */ - explicit RegisterJob(const QString& kind = QStringLiteral("user"), const Omittable<AuthenticationData>& auth = none, bool bindEmail = false, const QString& username = {}, const QString& password = {}, const QString& deviceId = {}, const QString& initialDeviceDisplayName = {}, bool inhibitLogin = false); - ~RegisterJob() override; - - // Result properties - - /// The fully-qualified Matrix user ID (MXID) that has been registered. - /// - /// Any user ID returned by this API must conform to the grammar given in the - /// `Matrix specification <https://matrix.org/docs/spec/appendices.html#user-identifiers>`_. - const QString& userId() const; - /// An access token for the account. - /// This access token can then be used to authorize other requests. - /// Required if the ``inhibit_login`` option is false. - const QString& accessToken() const; - /// The server_name of the homeserver on which the account has - /// been registered. - /// - /// **Deprecated**. Clients should extract the server_name from - /// ``user_id`` (by splitting at the first colon) if they require - /// it. Note also that ``homeserver`` is not spelt this way. - const QString& homeServer() const; - /// ID of the registered device. Will be the same as the - /// corresponding parameter in the request, if one was specified. - /// Required if the ``inhibit_login`` option is false. - const QString& deviceId() const; - - protected: - Status parseJson(const QJsonDocument& data) override; - - private: - class Private; - QScopedPointer<Private> d; - }; - - /// Begins the validation process for an email to be used during registration. + return loadFromJson<QString>("access_token"_ls); + } + + /// A refresh token for the account. This token can be used to + /// obtain a new access token when it expires by calling the + /// `/refresh` endpoint. /// - /// Proxies the Identity Service API ``validate/email/requestToken``, but - /// first checks that the given email address is not already associated - /// with an account on this homeserver. See the Identity Service API for - /// further information. - class RequestTokenToRegisterEmailJob : public BaseJob + /// Omitted if the `inhibit_login` option is true. + QString refreshToken() const { - public: - /*! Begins the validation process for an email to be used during registration. - * \param clientSecret - * A unique string generated by the client, and used to identify the - * validation attempt. It must be a string consisting of the characters - * ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it - * must not be empty. - * \param email - * The email address to validate. - * \param sendAttempt - * The server will only send an email if the ``send_attempt`` - * is a number greater than the most recent one which it has seen, - * scoped to that ``email`` + ``client_secret`` pair. This is to - * avoid repeatedly sending the same email in the case of request - * retries between the POSTing user and the identity server. - * The client should increment this value if they desire a new - * email (e.g. a reminder) to be sent. - * \param idServer - * The hostname of the identity server to communicate with. May - * optionally include a port. - * \param nextLink - * Optional. When the validation is completed, the identity - * server will redirect the user to this URL. - */ - explicit RequestTokenToRegisterEmailJob(const QString& clientSecret, const QString& email, int sendAttempt, const QString& idServer, const QString& nextLink = {}); - ~RequestTokenToRegisterEmailJob() override; - - // Result properties - - /// An email has been sent to the specified address. - /// Note that this may be an email containing the validation token or it may be informing - /// the user of an error. - const Sid& data() const; - - protected: - Status parseJson(const QJsonDocument& data) override; - - private: - class Private; - QScopedPointer<Private> d; - }; - - /// Requests a validation token be sent to the given phone number for the purpose of registering an account + return loadFromJson<QString>("refresh_token"_ls); + } + + /// The lifetime of the access token, in milliseconds. Once + /// the access token has expired a new access token can be + /// obtained by using the provided refresh token. If no + /// refresh token is provided, the client will need to re-log in + /// to obtain a new access token. If not given, the client can + /// assume that the access token will not expire. /// - /// Proxies the Identity Service API ``validate/msisdn/requestToken``, but - /// first checks that the given phone number is not already associated - /// with an account on this homeserver. See the Identity Service API for - /// further information. - class RequestTokenToRegisterMSISDNJob : public BaseJob + /// Omitted if the `inhibit_login` option is true. + Omittable<int> expiresInMs() const { - public: - /*! Requests a validation token be sent to the given phone number for the purpose of registering an account - * \param clientSecret - * A unique string generated by the client, and used to identify the - * validation attempt. It must be a string consisting of the characters - * ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it - * must not be empty. - * \param country - * The two-letter uppercase ISO country code that the number in - * ``phone_number`` should be parsed as if it were dialled from. - * \param phoneNumber - * The phone number to validate. - * \param sendAttempt - * The server will only send an SMS if the ``send_attempt`` is a - * number greater than the most recent one which it has seen, - * scoped to that ``country`` + ``phone_number`` + ``client_secret`` - * triple. This is to avoid repeatedly sending the same SMS in - * the case of request retries between the POSTing user and the - * identity server. The client should increment this value if - * they desire a new SMS (e.g. a reminder) to be sent. - * \param idServer - * The hostname of the identity server to communicate with. May - * optionally include a port. - * \param nextLink - * Optional. When the validation is completed, the identity - * server will redirect the user to this URL. - */ - explicit RequestTokenToRegisterMSISDNJob(const QString& clientSecret, const QString& country, const QString& phoneNumber, int sendAttempt, const QString& idServer, const QString& nextLink = {}); - ~RequestTokenToRegisterMSISDNJob() override; - - // Result properties - - /// An SMS message has been sent to the specified phone number. - /// Note that this may be an SMS message containing the validation token or it may be informing - /// the user of an error. - const Sid& data() const; - - protected: - Status parseJson(const QJsonDocument& data) override; - - private: - class Private; - QScopedPointer<Private> d; - }; - - /// Changes a user's password. - /// - /// Changes the password for an account on this homeserver. - /// - /// This API endpoint uses the `User-Interactive Authentication API`_. - /// - /// An access token should be submitted to this endpoint if the client has - /// an active session. - /// - /// The homeserver may change the flows available depending on whether a - /// valid access token is provided. - class ChangePasswordJob : public BaseJob + return loadFromJson<Omittable<int>>("expires_in_ms"_ls); + } + + /// ID of the registered device. Will be the same as the + /// corresponding parameter in the request, if one was specified. + /// Required if the `inhibit_login` option is false. + QString deviceId() const { return loadFromJson<QString>("device_id"_ls); } +}; + +/*! \brief Begins the validation process for an email to be used during + * registration. + * + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the email itself, either by sending a validation email + * itself or by using a service it has control over. + */ +class QUOTIENT_API RequestTokenToRegisterEmailJob : public BaseJob { +public: + /*! \brief Begins the validation process for an email to be used during + * registration. + * + * \param body + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the email itself, either by sending a validation email + * itself or by using a service it has control over. + */ + explicit RequestTokenToRegisterEmailJob(const EmailValidationData& body); + + // Result properties + + /// An email has been sent to the specified address. Note that this + /// may be an email containing the validation token or it may be + /// informing the user of an error. + RequestTokenResponse response() const { - public: - /*! Changes a user's password. - * \param newPassword - * The new password for the account. - * \param auth - * Additional authentication information for the user-interactive authentication API. - */ - explicit ChangePasswordJob(const QString& newPassword, const Omittable<AuthenticationData>& auth = none); - }; - - /// Requests a validation token be sent to the given email address for the purpose of resetting a user's password - /// - /// Proxies the Identity Service API ``validate/email/requestToken``, but - /// first checks that the given email address **is** associated with an account - /// on this homeserver. This API should be used to request - /// validation tokens when authenticating for the - /// `account/password` endpoint. This API's parameters and response are - /// identical to that of the HS API |/register/email/requestToken|_ except that - /// `M_THREEPID_NOT_FOUND` may be returned if no account matching the - /// given email address could be found. The server may instead send an - /// email to the given address prompting the user to create an account. - /// `M_THREEPID_IN_USE` may not be returned. - /// - /// .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` - /// - /// .. _/register/email/requestToken: #post-matrix-client-r0-register-email-requesttoken - class RequestTokenToResetPasswordEmailJob : public BaseJob + return fromJson<RequestTokenResponse>(jsonData()); + } +}; + +/*! \brief Requests a validation token be sent to the given phone number for the + * purpose of registering an account + * + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the phone number itself, either by sending a validation + * message itself or by using a service it has control over. + */ +class QUOTIENT_API RequestTokenToRegisterMSISDNJob : public BaseJob { +public: + /*! \brief Requests a validation token be sent to the given phone number for + * the purpose of registering an account + * + * \param body + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the phone number itself, either by sending a validation + * message itself or by using a service it has control over. + */ + explicit RequestTokenToRegisterMSISDNJob(const MsisdnValidationData& body); + + // Result properties + + /// An SMS message has been sent to the specified phone number. Note + /// that this may be an SMS message containing the validation token or + /// it may be informing the user of an error. + RequestTokenResponse response() const { - public: - /*! Requests a validation token be sent to the given email address for the purpose of resetting a user's password - * \param clientSecret - * A unique string generated by the client, and used to identify the - * validation attempt. It must be a string consisting of the characters - * ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it - * must not be empty. - * \param email - * The email address to validate. - * \param sendAttempt - * The server will only send an email if the ``send_attempt`` - * is a number greater than the most recent one which it has seen, - * scoped to that ``email`` + ``client_secret`` pair. This is to - * avoid repeatedly sending the same email in the case of request - * retries between the POSTing user and the identity server. - * The client should increment this value if they desire a new - * email (e.g. a reminder) to be sent. - * \param idServer - * The hostname of the identity server to communicate with. May - * optionally include a port. - * \param nextLink - * Optional. When the validation is completed, the identity - * server will redirect the user to this URL. - */ - explicit RequestTokenToResetPasswordEmailJob(const QString& clientSecret, const QString& email, int sendAttempt, const QString& idServer, const QString& nextLink = {}); - ~RequestTokenToResetPasswordEmailJob() override; - - // Result properties - - /// An email was sent to the given address. - const Sid& data() const; - - protected: - Status parseJson(const QJsonDocument& data) override; - - private: - class Private; - QScopedPointer<Private> d; - }; - - /// Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. - /// - /// Proxies the Identity Service API ``validate/msisdn/requestToken``, but - /// first checks that the given phone number **is** associated with an account - /// on this homeserver. This API should be used to request - /// validation tokens when authenticating for the - /// `account/password` endpoint. This API's parameters and response are - /// identical to that of the HS API |/register/msisdn/requestToken|_ except that - /// `M_THREEPID_NOT_FOUND` may be returned if no account matching the - /// given phone number could be found. The server may instead send an - /// SMS message to the given address prompting the user to create an account. - /// `M_THREEPID_IN_USE` may not be returned. - /// - /// .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` - /// - /// .. _/register/msisdn/requestToken: #post-matrix-client-r0-register-email-requesttoken - class RequestTokenToResetPasswordMSISDNJob : public BaseJob + return fromJson<RequestTokenResponse>(jsonData()); + } +}; + +/*! \brief Changes a user's password. + * + * Changes the password for an account on this homeserver. + * + * This API endpoint uses the [User-Interactive Authentication + * API](/client-server-api/#user-interactive-authentication-api) to ensure the + * user changing the password is actually the owner of the account. + * + * An access token should be submitted to this endpoint if the client has + * an active session. + * + * The homeserver may change the flows available depending on whether a + * valid access token is provided. The homeserver SHOULD NOT revoke the + * access token provided in the request. Whether other access tokens for + * the user are revoked depends on the request parameters. + */ +class QUOTIENT_API ChangePasswordJob : public BaseJob { +public: + /*! \brief Changes a user's password. + * + * \param newPassword + * The new password for the account. + * + * \param logoutDevices + * Whether the user's other access tokens, and their associated devices, + * should be revoked if the request succeeds. + * + * When `false`, the server can still take advantage of the [soft logout + * method](/client-server-api/#soft-logout) for the user's remaining + * devices. + * + * \param auth + * Additional authentication information for the user-interactive + * authentication API. + */ + explicit ChangePasswordJob(const QString& newPassword, + bool logoutDevices = true, + const Omittable<AuthenticationData>& auth = none); +}; + +/*! \brief Requests a validation token be sent to the given email address for + * the purpose of resetting a user's password + * + * The homeserver must check that the given email address **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * `/account/password` endpoint. + * + * This API's parameters and response are identical to that of the + * [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken) + * endpoint, except that + * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * given email address could be found. The server may instead send an + * email to the given address prompting the user to create an account. + * `M_THREEPID_IN_USE` may not be returned. + * + * The homeserver should validate the email itself, either by sending a + * validation email itself or by using a service it has control over. + */ +class QUOTIENT_API RequestTokenToResetPasswordEmailJob : public BaseJob { +public: + /*! \brief Requests a validation token be sent to the given email address + * for the purpose of resetting a user's password + * + * \param body + * The homeserver must check that the given email address **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * `/account/password` endpoint. + * + * This API's parameters and response are identical to that of the + * [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken) + * endpoint, except that + * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * given email address could be found. The server may instead send an + * email to the given address prompting the user to create an account. + * `M_THREEPID_IN_USE` may not be returned. + * + * The homeserver should validate the email itself, either by sending a + * validation email itself or by using a service it has control over. + */ + explicit RequestTokenToResetPasswordEmailJob(const EmailValidationData& body); + + // Result properties + + /// An email was sent to the given address. + RequestTokenResponse response() const { - public: - /*! Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. - * \param clientSecret - * A unique string generated by the client, and used to identify the - * validation attempt. It must be a string consisting of the characters - * ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it - * must not be empty. - * \param country - * The two-letter uppercase ISO country code that the number in - * ``phone_number`` should be parsed as if it were dialled from. - * \param phoneNumber - * The phone number to validate. - * \param sendAttempt - * The server will only send an SMS if the ``send_attempt`` is a - * number greater than the most recent one which it has seen, - * scoped to that ``country`` + ``phone_number`` + ``client_secret`` - * triple. This is to avoid repeatedly sending the same SMS in - * the case of request retries between the POSTing user and the - * identity server. The client should increment this value if - * they desire a new SMS (e.g. a reminder) to be sent. - * \param idServer - * The hostname of the identity server to communicate with. May - * optionally include a port. - * \param nextLink - * Optional. When the validation is completed, the identity - * server will redirect the user to this URL. - */ - explicit RequestTokenToResetPasswordMSISDNJob(const QString& clientSecret, const QString& country, const QString& phoneNumber, int sendAttempt, const QString& idServer, const QString& nextLink = {}); - ~RequestTokenToResetPasswordMSISDNJob() override; - - // Result properties - - /// An SMS message was sent to the given phone number. - const Sid& data() const; - - protected: - Status parseJson(const QJsonDocument& data) override; - - private: - class Private; - QScopedPointer<Private> d; - }; - - /// Deactivate a user's account. - /// - /// Deactivate the user's account, removing all ability for the user to - /// login again. - /// - /// This API endpoint uses the `User-Interactive Authentication API`_. - /// - /// An access token should be submitted to this endpoint if the client has - /// an active session. - /// - /// The homeserver may change the flows available depending on whether a - /// valid access token is provided. - class DeactivateAccountJob : public BaseJob + return fromJson<RequestTokenResponse>(jsonData()); + } +}; + +/*! \brief Requests a validation token be sent to the given phone number for the + * purpose of resetting a user's password. + * + * The homeserver must check that the given phone number **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * `/account/password` endpoint. + * + * This API's parameters and response are identical to that of the + * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) + * endpoint, except that + * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * given phone number could be found. The server may instead send the SMS + * to the given phone number prompting the user to create an account. + * `M_THREEPID_IN_USE` may not be returned. + * + * The homeserver should validate the phone number itself, either by sending a + * validation message itself or by using a service it has control over. + */ +class QUOTIENT_API RequestTokenToResetPasswordMSISDNJob : public BaseJob { +public: + /*! \brief Requests a validation token be sent to the given phone number for + * the purpose of resetting a user's password. + * + * \param body + * The homeserver must check that the given phone number **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * `/account/password` endpoint. + * + * This API's parameters and response are identical to that of the + * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) + * endpoint, except that + * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * given phone number could be found. The server may instead send the SMS + * to the given phone number prompting the user to create an account. + * `M_THREEPID_IN_USE` may not be returned. + * + * The homeserver should validate the phone number itself, either by + * sending a validation message itself or by using a service it has control + * over. + */ + explicit RequestTokenToResetPasswordMSISDNJob( + const MsisdnValidationData& body); + + // Result properties + + /// An SMS message was sent to the given phone number. + RequestTokenResponse response() const { - public: - /*! Deactivate a user's account. - * \param auth - * Additional authentication information for the user-interactive authentication API. - */ - explicit DeactivateAccountJob(const Omittable<AuthenticationData>& auth = none); - }; - - /// Checks to see if a username is available on the server. - /// - /// Checks to see if a username is available, and valid, for the server. - /// - /// The server should check to ensure that, at the time of the request, the - /// username requested is available for use. This includes verifying that an - /// application service has not claimed the username and that the username - /// fits the server's desired requirements (for example, a server could dictate - /// that it does not permit usernames with underscores). - /// - /// Matrix clients may wish to use this API prior to attempting registration, - /// however the clients must also be aware that using this API does not normally - /// reserve the username. This can mean that the username becomes unavailable - /// between checking its availability and attempting to register it. - class CheckUsernameAvailabilityJob : public BaseJob + return fromJson<RequestTokenResponse>(jsonData()); + } +}; + +/*! \brief Deactivate a user's account. + * + * Deactivate the user's account, removing all ability for the user to + * login again. + * + * This API endpoint uses the [User-Interactive Authentication + * API](/client-server-api/#user-interactive-authentication-api). + * + * An access token should be submitted to this endpoint if the client has + * an active session. + * + * The homeserver may change the flows available depending on whether a + * valid access token is provided. + * + * Unlike other endpoints, this endpoint does not take an `id_access_token` + * parameter because the homeserver is expected to sign the request to the + * identity server instead. + */ +class QUOTIENT_API DeactivateAccountJob : public BaseJob { +public: + /*! \brief Deactivate a user's account. + * + * \param auth + * Additional authentication information for the user-interactive + * authentication API. + * + * \param idServer + * The identity server to unbind all of the user's 3PIDs from. + * If not provided, the homeserver MUST use the `id_server` + * that was originally use to bind each identifier. If the + * homeserver does not know which `id_server` that was, + * it must return an `id_server_unbind_result` of + * `no-support`. + */ + explicit DeactivateAccountJob( + const Omittable<AuthenticationData>& auth = none, + const QString& idServer = {}); + + // Result properties + + /// An indicator as to whether or not the homeserver was able to unbind + /// the user's 3PIDs from the identity server(s). `success` indicates + /// that all identifiers have been unbound from the identity server while + /// `no-support` indicates that one or more identifiers failed to unbind + /// due to the identity server refusing the request or the homeserver + /// being unable to determine an identity server to unbind from. This + /// must be `success` if the homeserver has no identifiers to unbind + /// for the user. + QString idServerUnbindResult() const + { + return loadFromJson<QString>("id_server_unbind_result"_ls); + } +}; + +/*! \brief Checks to see if a username is available on the server. + * + * Checks to see if a username is available, and valid, for the server. + * + * The server should check to ensure that, at the time of the request, the + * username requested is available for use. This includes verifying that an + * application service has not claimed the username and that the username + * fits the server's desired requirements (for example, a server could dictate + * that it does not permit usernames with underscores). + * + * Matrix clients may wish to use this API prior to attempting registration, + * however the clients must also be aware that using this API does not normally + * reserve the username. This can mean that the username becomes unavailable + * between checking its availability and attempting to register it. + */ +class QUOTIENT_API CheckUsernameAvailabilityJob : public BaseJob { +public: + /*! \brief Checks to see if a username is available on the server. + * + * \param username + * The username to check the availability of. + */ + explicit CheckUsernameAvailabilityJob(const QString& username); + + /*! \brief Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for CheckUsernameAvailabilityJob + * is necessary but the job itself isn't. + */ + static QUrl makeRequestUrl(QUrl baseUrl, const QString& username); + + // Result properties + + /// A flag to indicate that the username is available. This should always + /// be `true` when the server replies with 200 OK. + Omittable<bool> available() const { - public: - /*! Checks to see if a username is available on the server. - * \param username - * The username to check the availability of. - */ - explicit CheckUsernameAvailabilityJob(const QString& username); - - /*! Construct a URL without creating a full-fledged job object - * - * This function can be used when a URL for - * CheckUsernameAvailabilityJob is necessary but the job - * itself isn't. - */ - static QUrl makeRequestUrl(QUrl baseUrl, const QString& username); - - ~CheckUsernameAvailabilityJob() override; - - // Result properties - - /// A flag to indicate that the username is available. This should always - /// be ``true`` when the server replies with 200 OK. - bool available() const; - - protected: - Status parseJson(const QJsonDocument& data) override; - - private: - class Private; - QScopedPointer<Private> d; - }; -} // namespace QMatrixClient + return loadFromJson<Omittable<bool>>("available"_ls); + } +}; + +} // namespace Quotient |