/******************************************************************************
* THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
*/
#pragma once
#include "converters.h"
#include "csapi/../identity/definitions/sid.h"
#include "csapi/definitions/auth_data.h"
#include "jobs/basejob.h"
namespace Quotient
{
// 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<AuthenticationData>& auth = none,
Omittable<bool> bindEmail = none,
const QString& username = {},
const QString& password = {},
const QString& deviceId = {},
const QString& initialDeviceDisplayName = {},
Omittable<bool> 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
/// <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.
/*!
* 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<Private> 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<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
{
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
{
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
{
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
{
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
{
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<bool> available() const;
protected:
Status parseJson(const QJsonDocument& data) override;
private:
class Private;
QScopedPointer<Private> d;
};
} // namespace Quotient