diff options
Diffstat (limited to 'lib/csapi/administrative_contact.h')
| -rw-r--r-- | lib/csapi/administrative_contact.h | 155 |
1 files changed, 117 insertions, 38 deletions
diff --git a/lib/csapi/administrative_contact.h b/lib/csapi/administrative_contact.h index 112b81cc..3fb3d44c 100644 --- a/lib/csapi/administrative_contact.h +++ b/lib/csapi/administrative_contact.h @@ -6,6 +6,7 @@ #include "jobs/basejob.h" +#include "csapi/../identity/definitions/sid.h" #include "converters.h" #include <QtCore/QVector> @@ -14,12 +15,12 @@ namespace QMatrixClient // Operations /// Gets a list of a user's third party identifiers. - /// + /// /// Gets a list of the third party identifiers that the homeserver has /// associated with the user's account. /// /// This is *not* the same as the list of third party identifiers bound to - /// the user's Matrix ID in Identity Servers. + /// the user's Matrix ID in identity servers. /// /// Identifiers in this list may be used by the homeserver as, for example, /// identifiers that it will accept to reset the user's account password. @@ -32,7 +33,7 @@ namespace QMatrixClient /// associated with the user's account. /// /// This is *not* the same as the list of third party identifiers bound to - /// the user's Matrix ID in Identity Servers. + /// the user's Matrix ID in identity servers. /// /// Identifiers in this list may be used by the homeserver as, for example, /// identifiers that it will accept to reset the user's account password. @@ -42,6 +43,11 @@ namespace QMatrixClient QString medium; /// The third party identifier address. QString address; + /// The timestamp, in milliseconds, when the identifier was + /// validated by the identity server. + qint64 validatedAt; + /// The timestamp, in milliseconds, when the homeserver associated the third party identifier with the user. + qint64 addedAt; }; // Construction/destruction @@ -64,7 +70,7 @@ namespace QMatrixClient /// associated with the user's account. /// /// This is *not* the same as the list of third party identifiers bound to - /// the user's Matrix ID in Identity Servers. + /// the user's Matrix ID in identity servers. /// /// Identifiers in this list may be used by the homeserver as, for example, /// identifiers that it will accept to reset the user's account password. @@ -79,7 +85,7 @@ namespace QMatrixClient }; /// Adds contact information to the user's account. - /// + /// /// Adds contact information to the user's account. class Post3PIDsJob : public BaseJob { @@ -89,20 +95,20 @@ namespace QMatrixClient /// The third party credentials to associate with the account. struct ThreePidCredentials { - /// The client secret used in the session with the Identity Server. + /// The client secret used in the session with the identity server. QString clientSecret; - /// The Identity Server to use. + /// The identity server to use. QString idServer; - /// The session identifier given by the Identity Server. + /// The session identifier given by the identity server. QString sid; }; // Construction/destruction /*! Adds contact information to the user's account. - * \param threePidCreds + * \param threePidCreds * The third party credentials to associate with the account. - * \param bind + * \param bind * Whether the homeserver should also bind this third party * identifier to the account's Matrix ID with the passed identity * server. Default: ``false``. @@ -110,49 +116,122 @@ namespace QMatrixClient explicit Post3PIDsJob(const ThreePidCredentials& threePidCreds, bool bind = false); }; - /// Requests a validation token be sent to the given email address for the purpose of adding an email address to an account - /// - /// Proxies the identity server API ``validate/email/requestToken``, but + /// Deletes a third party identifier from the user's account + /// + /// Removes a third party identifier from the user's account. This might not + /// cause an unbind of the identifier from the identity server. + class Delete3pidFromAccountJob : public BaseJob + { + public: + /*! Deletes a third party identifier from the user's account + * \param medium + * The medium of the third party identifier being removed. + * \param address + * The third party address being removed. + */ + explicit Delete3pidFromAccountJob(const QString& medium, const QString& address); + }; + + /// Begins the validation process for an email address for association with the user's account. + /// + /// 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 Home Server. This API should be used to request + /// with an account on this homeserver. This API should be used to request /// validation tokens when adding an email address to an account. This API's - /// parameters and response is identical to that of the HS API - /// |/register/email/requestToken|_ endpoint. + /// parameters and response are identical to that of the |/register/email/requestToken|_ + /// endpoint. class RequestTokenTo3PIDEmailJob : public BaseJob { public: - explicit RequestTokenTo3PIDEmailJob(); - - /*! Construct a URL without creating a full-fledged job object - * - * This function can be used when a URL for - * RequestTokenTo3PIDEmailJob is necessary but the job - * itself isn't. + /*! Begins the validation process for an email address for association with the user's 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 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. */ - static QUrl makeRequestUrl(QUrl baseUrl); + explicit RequestTokenTo3PIDEmailJob(const QString& clientSecret, const QString& email, int sendAttempt, const QString& idServer, const QString& nextLink = {}); + ~RequestTokenTo3PIDEmailJob() 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 email address for the purpose of adding a phone number to an account. - /// - /// Proxies the identity server API ``validate/msisdn/requestToken``, but + /// Begins the validation process for a phone number for association with the user's 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 Home Server. This API should be used to request + /// with an account on this homeserver. This API should be used to request /// validation tokens when adding a phone number to an account. This API's - /// parameters and response is identical to that of the HS API - /// |/register/msisdn/requestToken|_ endpoint. + /// parameters and response are identical to that of the |/register/msisdn/requestToken|_ + /// endpoint. class RequestTokenTo3PIDMSISDNJob : public BaseJob { public: - explicit RequestTokenTo3PIDMSISDNJob(); - - /*! Construct a URL without creating a full-fledged job object - * - * This function can be used when a URL for - * RequestTokenTo3PIDMSISDNJob is necessary but the job - * itself isn't. + /*! Begins the validation process for a phone number for association with the user's 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. */ - static QUrl makeRequestUrl(QUrl baseUrl); + explicit RequestTokenTo3PIDMSISDNJob(const QString& clientSecret, const QString& country, const QString& phoneNumber, int sendAttempt, const QString& idServer, const QString& nextLink = {}); + ~RequestTokenTo3PIDMSISDNJob() 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; }; } // namespace QMatrixClient |