diff options
Diffstat (limited to 'lib/csapi/registration.h')
| -rw-r--r-- | lib/csapi/registration.h | 174 |
1 files changed, 168 insertions, 6 deletions
diff --git a/lib/csapi/registration.h b/lib/csapi/registration.h index a4974177..53b2de9d 100644 --- a/lib/csapi/registration.h +++ b/lib/csapi/registration.h @@ -13,17 +13,90 @@ 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 ID 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. + */ explicit RegisterJob(const QString& kind = QStringLiteral("user"), const QJsonObject& auth = {}, bool bindEmail = false, const QString& username = {}, const QString& password = {}, const QString& deviceId = {}, const QString& initialDeviceDisplayName = {}); ~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. 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. const QString& deviceId() const; protected: @@ -34,46 +107,133 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Requests a validation token be sent to the given email address for the purpose of registering an account + /// + /// Proxies the identity server API ``validate/email/requestToken``, but + /// first checks that the given email address is not already associated + /// with an account on this Home Server. Note that, for consistency, + /// this API takes JSON objects, though the Identity Server API takes + /// ``x-www-form-urlencoded`` parameters. See the Identity Server API for + /// further information. class RequestTokenToRegisterJob : public BaseJob { public: + /*! Requests a validation token be sent to the given email address for the purpose of registering an account + * \param clientSecret + * Client-generated secret string used to protect this session + * \param email + * The email address + * \param sendAttempt + * Used to distinguish protocol level retries from requests to re-send the email. + * \param idServer + * The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default. + */ explicit RequestTokenToRegisterJob(const QString& clientSecret, const QString& email, int sendAttempt, const QString& idServer = {}); }; + /// 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 QJsonObject& auth = {}); }; + /// Requests a validation token be sent to the given email address for the purpose of resetting a user's password + /// + /// Proxies the identity server API ``validate/email/requestToken``, but + /// first checks that the given email address **is** associated with an account + /// on this Home Server. 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 RequestTokenToResetPasswordJob : public BaseJob { public: explicit RequestTokenToResetPasswordJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * RequestTokenToResetPasswordJob. This function can be used when - * a URL for RequestTokenToResetPasswordJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * RequestTokenToResetPasswordJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); }; + /// 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 QJsonObject& auth = {}); }; + /// 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 out of baseUrl and usual parameters passed to - * CheckUsernameAvailabilityJob. This function can be used when - * a URL for CheckUsernameAvailabilityJob is necessary but the job + /*! 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); @@ -82,6 +242,8 @@ namespace QMatrixClient // 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: |