/****************************************************************************** * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN */ #pragma once #include "jobs/basejob.h" #include "converters.h" #include "csapi/../identity/definitions/sid.h" #include "csapi/definitions/auth_data.h" namespace QMatrixClient { // Operations /// Register for an account on this homeserver. /// /// 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 { 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& auth = none, Omittable bindEmail = none, const QString& username = {}, const QString& password = {}, const QString& deviceId = {}, const QString& initialDeviceDisplayName = {}, Omittable inhibitLogin = none); ~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 /// `_. 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 d; }; /// Begins the validation process for an email to be used during /// registration. /// /// 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 { 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 d; }; /// Requests a validation token be sent to the given phone number for the /// purpose of registering an account /// /// 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 { 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 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 { 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& 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 { 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 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 { 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 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 { public: /*! Deactivate a user's account. * \param auth * Additional authentication information for the user-interactive * authentication API. */ explicit DeactivateAccountJob( const Omittable& 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 { 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. Omittable available() const; protected: Status parseJson(const QJsonDocument& data) override; private: class Private; QScopedPointer d; }; } // namespace QMatrixClient