diff options
50 files changed, 2211 insertions, 160 deletions
diff --git a/lib/csapi/account-data.h b/lib/csapi/account-data.h index 9ee565df..d8ae0aa1 100644 --- a/lib/csapi/account-data.h +++ b/lib/csapi/account-data.h @@ -12,15 +12,47 @@ namespace QMatrixClient { // Operations + /// Set some account_data for the user. + /// + /// Set some account_data for the client. This config is only visible to the user + /// that set the account_data. The config will be synced to clients in the + /// top-level ``account_data``. class SetAccountDataJob : public BaseJob { public: + /*! Set some account_data for the user. + * \param userId + * The id of the user to set account_data for. The access token must be + * authorized to make requests for this user id. + * \param type + * The event type of the account_data to set. Custom types should be + * namespaced to avoid clashes. + * \param content + * The content of the account_data + */ explicit SetAccountDataJob(const QString& userId, const QString& type, const QJsonObject& content = {}); }; + /// Set some account_data for the user. + /// + /// Set some account_data for the client on a given room. This config is only + /// visible to the user that set the account_data. The config will be synced to + /// clients in the per-room ``account_data``. class SetAccountDataPerRoomJob : public BaseJob { public: + /*! Set some account_data for the user. + * \param userId + * The id of the user to set account_data for. The access token must be + * authorized to make requests for this user id. + * \param roomId + * The id of the room to set account_data on. + * \param type + * The event type of the account_data to set. Custom types should be + * namespaced to avoid clashes. + * \param content + * The content of the account_data + */ explicit SetAccountDataPerRoomJob(const QString& userId, const QString& roomId, const QString& type, const QJsonObject& content = {}); }; } // namespace QMatrixClient diff --git a/lib/csapi/admin.h b/lib/csapi/admin.h index 087eabf0..b1b23ded 100644 --- a/lib/csapi/admin.h +++ b/lib/csapi/admin.h @@ -14,35 +14,67 @@ namespace QMatrixClient { // Operations + /// Gets information about a particular user. + /// + /// Gets information about a particular user. + /// + /// This API may be restricted to only be called by the user being looked + /// up, or by a server admin. Server-local administrator privileges are not + /// specified in this document. class GetWhoIsJob : public BaseJob { public: // Inner data structures + /// Gets information about a particular user. + /// + /// This API may be restricted to only be called by the user being looked + /// up, or by a server admin. Server-local administrator privileges are not + /// specified in this document. struct ConnectionInfo { + /// Most recently seen IP address of the session. QString ip; + /// Unix timestamp that the session was last active. Omittable<qint64> lastSeen; + /// User agent string last seen in the session. QString userAgent; }; + /// Gets information about a particular user. + /// + /// This API may be restricted to only be called by the user being looked + /// up, or by a server admin. Server-local administrator privileges are not + /// specified in this document. struct SessionInfo { + /// Information particular connections in the session. QVector<ConnectionInfo> connections; }; + /// Gets information about a particular user. + /// + /// This API may be restricted to only be called by the user being looked + /// up, or by a server admin. Server-local administrator privileges are not + /// specified in this document. struct DeviceInfo { + /// A user's sessions (i.e. what they did with an access token from one login). QVector<SessionInfo> sessions; }; // Construction/destruction + /*! Gets information about a particular user. + * \param userId + * The user to look up. + */ explicit GetWhoIsJob(const QString& userId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetWhoIsJob. This function can be used when - * a URL for GetWhoIsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetWhoIsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId); @@ -51,7 +83,9 @@ namespace QMatrixClient // Result properties + /// The Matrix user ID of the user. const QString& userId() const; + /// Each key is an identitfier for one of the user's devices. const QHash<QString, DeviceInfo>& devices() const; protected: diff --git a/lib/csapi/administrative_contact.h b/lib/csapi/administrative_contact.h index 57d11d34..b9a5ee4b 100644 --- a/lib/csapi/administrative_contact.h +++ b/lib/csapi/administrative_contact.h @@ -13,14 +13,34 @@ 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. + /// + /// 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. class GetAccount3PIDsJob : public BaseJob { public: // Inner data structures + /// 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. + /// + /// 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. struct ThirdPartyIdentifier { + /// The medium of the third party identifier. QString medium; + /// The third party identifier address. QString address; }; @@ -28,9 +48,10 @@ namespace QMatrixClient explicit GetAccount3PIDsJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetAccount3PIDsJob. This function can be used when - * a URL for GetAccount3PIDsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetAccount3PIDsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -39,6 +60,14 @@ namespace QMatrixClient // Result properties + /// 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. + /// + /// 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. const QVector<ThirdPartyIdentifier>& threepids() const; protected: @@ -49,31 +78,55 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Adds contact information to the user's account. + /// + /// Adds contact information to the user's account. class Post3PIDsJob : public BaseJob { public: // Inner data structures + /// The third party credentials to associate with the account. struct ThreePidCredentials { + /// The client secret used in the session with the Identity Server. QString clientSecret; + /// The Identity Server to use. QString idServer; + /// The session identifier given by the Identity Server. QString sid; }; // Construction/destruction + /*! Adds contact information to the user's account. + * \param threePidCreds + * The third party credentials to associate with the account. + * \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``. + */ 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 + /// 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 + /// 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. class RequestTokenTo3PIDJob : public BaseJob { public: explicit RequestTokenTo3PIDJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * RequestTokenTo3PIDJob. This function can be used when - * a URL for RequestTokenTo3PIDJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * RequestTokenTo3PIDJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); diff --git a/lib/csapi/banning.h b/lib/csapi/banning.h index 0f6eabf8..196ddf66 100644 --- a/lib/csapi/banning.h +++ b/lib/csapi/banning.h @@ -11,15 +11,42 @@ namespace QMatrixClient { // Operations + /// Ban a user in the room. + /// + /// Ban a user in the room. If the user is currently in the room, also kick them. + /// + /// When a user is banned from a room, they may not join it or be invited to it until they are unbanned. + /// + /// The caller must have the required power level in order to perform this operation. class BanJob : public BaseJob { public: + /*! Ban a user in the room. + * \param roomId + * The room identifier (not alias) from which the user should be banned. + * \param userId + * The fully qualified user ID of the user being banned. + * \param reason + * The reason the user has been banned. This will be supplied as the ``reason`` on the target's updated `m.room.member`_ event. + */ explicit BanJob(const QString& roomId, const QString& userId, const QString& reason = {}); }; + /// Unban a user from the room. + /// + /// Unban a user from the room. This allows them to be invited to the room, + /// and join if they would otherwise be allowed to join according to its join rules. + /// + /// The caller must have the required power level in order to perform this operation. class UnbanJob : public BaseJob { public: + /*! Unban a user from the room. + * \param roomId + * The room identifier (not alias) from which the user should be unbanned. + * \param userId + * The fully qualified user ID of the user being unbanned. + */ explicit UnbanJob(const QString& roomId, const QString& userId); }; } // namespace QMatrixClient diff --git a/lib/csapi/content-repo.h b/lib/csapi/content-repo.h index 6a871893..85d7cb49 100644 --- a/lib/csapi/content-repo.h +++ b/lib/csapi/content-repo.h @@ -13,14 +13,23 @@ namespace QMatrixClient { // Operations + /// Upload some content to the content repository. class UploadContentJob : public BaseJob { public: + /*! Upload some content to the content repository. + * \param content + * \param filename + * The name of the file being uploaded + * \param contentType + * The content type of the file being uploaded + */ explicit UploadContentJob(QIODevice* content, const QString& filename = {}, const QString& contentType = {}); ~UploadContentJob() override; // Result properties + /// The MXC URI to the uploaded content. const QString& contentUri() const; protected: @@ -31,14 +40,26 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Download content from the content repository. class GetContentJob : public BaseJob { public: + /*! Download content from the content repository. + * \param serverName + * The server name from the ``mxc://`` URI (the authoritory component) + * \param mediaId + * The media ID from the ``mxc://`` URI (the path component) + * \param allowRemote + * Indicates to the server that it should not attempt to fetch the media if it is deemed + * remote. This is to prevent routing loops where the server contacts itself. Defaults to + * true if not provided. + */ explicit GetContentJob(const QString& serverName, const QString& mediaId, bool allowRemote = true); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetContentJob. This function can be used when - * a URL for GetContentJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetContentJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& serverName, const QString& mediaId, bool allowRemote = true); @@ -47,8 +68,11 @@ namespace QMatrixClient // Result properties + /// The content type of the file that was previously uploaded. const QString& contentType() const; + /// The name of the file that was previously uploaded, if set. const QString& contentDisposition() const; + /// The content that was previously uploaded. QIODevice* data() const; protected: @@ -59,14 +83,28 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Download content from the content repository as a given filename. class GetContentOverrideNameJob : public BaseJob { public: + /*! Download content from the content repository as a given filename. + * \param serverName + * The server name from the ``mxc://`` URI (the authoritory component) + * \param mediaId + * The media ID from the ``mxc://`` URI (the path component) + * \param fileName + * The filename to give in the Content-Disposition + * \param allowRemote + * Indicates to the server that it should not attempt to fetch the media if it is deemed + * remote. This is to prevent routing loops where the server contacts itself. Defaults to + * true if not provided. + */ explicit GetContentOverrideNameJob(const QString& serverName, const QString& mediaId, const QString& fileName, bool allowRemote = true); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetContentOverrideNameJob. This function can be used when - * a URL for GetContentOverrideNameJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetContentOverrideNameJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& serverName, const QString& mediaId, const QString& fileName, bool allowRemote = true); @@ -75,8 +113,11 @@ namespace QMatrixClient // Result properties + /// The content type of the file that was previously uploaded. const QString& contentType() const; + /// The name of file given in the request const QString& contentDisposition() const; + /// The content that was previously uploaded. QIODevice* data() const; protected: @@ -87,14 +128,34 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Download a thumbnail of the content from the content repository. class GetContentThumbnailJob : public BaseJob { public: + /*! Download a thumbnail of the content from the content repository. + * \param serverName + * The server name from the ``mxc://`` URI (the authoritory component) + * \param mediaId + * The media ID from the ``mxc://`` URI (the path component) + * \param width + * The *desired* width of the thumbnail. The actual thumbnail may not + * match the size specified. + * \param height + * The *desired* height of the thumbnail. The actual thumbnail may not + * match the size specified. + * \param method + * The desired resizing method. + * \param allowRemote + * Indicates to the server that it should not attempt to fetch the media if it is deemed + * remote. This is to prevent routing loops where the server contacts itself. Defaults to + * true if not provided. + */ explicit GetContentThumbnailJob(const QString& serverName, const QString& mediaId, int width, int height, const QString& method = {}, bool allowRemote = true); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetContentThumbnailJob. This function can be used when - * a URL for GetContentThumbnailJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetContentThumbnailJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& serverName, const QString& mediaId, int width, int height, const QString& method = {}, bool allowRemote = true); @@ -103,7 +164,9 @@ namespace QMatrixClient // Result properties + /// The content type of the thumbnail. const QString& contentType() const; + /// A thumbnail of the requested content. QIODevice* data() const; protected: @@ -114,14 +177,24 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Get information about a URL for a client class GetUrlPreviewJob : public BaseJob { public: + /*! Get information about a URL for a client + * \param url + * The URL to get a preview of + * \param ts + * The preferred point in time to return a preview for. The server may + * return a newer version if it does not have the requested version + * available. + */ explicit GetUrlPreviewJob(const QString& url, Omittable<qint64> ts = none); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetUrlPreviewJob. This function can be used when - * a URL for GetUrlPreviewJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetUrlPreviewJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& url, Omittable<qint64> ts = none); @@ -130,7 +203,9 @@ namespace QMatrixClient // Result properties + /// The byte-size of the image. Omitted if there is no image attached. Omittable<qint64> matrixImageSize() const; + /// An MXC URI to the image. Omitted if there is no image. const QString& ogImage() const; protected: @@ -141,14 +216,27 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Get the configuration for the content repository. + /// + /// This endpoint allows clients to retrieve the configuration of the content + /// repository, such as upload limitations. + /// Clients SHOULD use this as a guide when using content repository endpoints. + /// All values are intentionally left optional. Clients SHOULD follow + /// the advice given in the field description when the field is not available. + /// + /// **NOTE:** Both clients and server administrators should be aware that proxies + /// between the client and the server may affect the apparent behaviour of content + /// repository APIs, for example, proxies may enforce a lower upload size limit + /// than is advertised by the server on this endpoint. class GetConfigJob : public BaseJob { public: explicit GetConfigJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetConfigJob. This function can be used when - * a URL for GetConfigJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetConfigJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -157,6 +245,9 @@ namespace QMatrixClient // Result properties + /// The maximum size an upload can be in bytes. + /// Clients SHOULD use this as a guide when uploading content. + /// If not listed or null, the size limit should be treated as unknown. Omittable<double> uploadSize() const; protected: diff --git a/lib/csapi/create_room.h b/lib/csapi/create_room.h index f7b7e800..ee09fb35 100644 --- a/lib/csapi/create_room.h +++ b/lib/csapi/create_room.h @@ -14,32 +14,174 @@ namespace QMatrixClient { // Operations + /// Create a new room + /// + /// Create a new room with various configuration options. + /// + /// The server MUST apply the normal state resolution rules when creating + /// the new room, including checking power levels for each event. It MUST + /// apply the events implied by the request in the following order: + /// + /// 0. A default ``m.room.power_levels`` event, giving the room creator + /// (and not other members) permission to send state events. + /// + /// 1. Events set by the ``preset``. + /// + /// 2. Events listed in ``initial_state``, in the order that they are + /// listed. + /// + /// 3. Events implied by ``name`` and ``topic``. + /// + /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// + /// The available presets do the following with respect to room state: + /// + /// ======================== ============== ====================== ================ ========= + /// Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other + /// ======================== ============== ====================== ================ ========= + /// ``private_chat`` ``invite`` ``shared`` ``can_join`` + /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. + /// ``public_chat`` ``public`` ``shared`` ``forbidden`` + /// ======================== ============== ====================== ================ ========= class CreateRoomJob : public BaseJob { public: // Inner data structures + /// Create a new room with various configuration options. + /// + /// The server MUST apply the normal state resolution rules when creating + /// the new room, including checking power levels for each event. It MUST + /// apply the events implied by the request in the following order: + /// + /// 0. A default ``m.room.power_levels`` event, giving the room creator + /// (and not other members) permission to send state events. + /// + /// 1. Events set by the ``preset``. + /// + /// 2. Events listed in ``initial_state``, in the order that they are + /// listed. + /// + /// 3. Events implied by ``name`` and ``topic``. + /// + /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// + /// The available presets do the following with respect to room state: + /// + /// ======================== ============== ====================== ================ ========= + /// Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other + /// ======================== ============== ====================== ================ ========= + /// ``private_chat`` ``invite`` ``shared`` ``can_join`` + /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. + /// ``public_chat`` ``public`` ``shared`` ``forbidden`` + /// ======================== ============== ====================== ================ ========= struct Invite3pid { + /// The hostname+port of the identity server which should be used for third party identifier lookups. QString idServer; + /// The kind of address being passed in the address field, for example ``email``. QString medium; + /// The invitee's third party identifier. QString address; }; + /// Create a new room with various configuration options. + /// + /// The server MUST apply the normal state resolution rules when creating + /// the new room, including checking power levels for each event. It MUST + /// apply the events implied by the request in the following order: + /// + /// 0. A default ``m.room.power_levels`` event, giving the room creator + /// (and not other members) permission to send state events. + /// + /// 1. Events set by the ``preset``. + /// + /// 2. Events listed in ``initial_state``, in the order that they are + /// listed. + /// + /// 3. Events implied by ``name`` and ``topic``. + /// + /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// + /// The available presets do the following with respect to room state: + /// + /// ======================== ============== ====================== ================ ========= + /// Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other + /// ======================== ============== ====================== ================ ========= + /// ``private_chat`` ``invite`` ``shared`` ``can_join`` + /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. + /// ``public_chat`` ``public`` ``shared`` ``forbidden`` + /// ======================== ============== ====================== ================ ========= struct StateEvent { + /// The type of event to send. QString type; + /// The state_key of the state event. Defaults to an empty string. QString stateKey; + /// The content of the event. QJsonObject content; }; // Construction/destruction + /*! Create a new room + * \param visibility + * A ``public`` visibility indicates that the room will be shown + * in the published room list. A ``private`` visibility will hide + * the room from the published room list. Rooms default to + * ``private`` visibility if this key is not included. NB: This + * should not be confused with ``join_rules`` which also uses the + * word ``public``. + * \param roomAliasName + * The desired room alias **local part**. If this is included, a + * room alias will be created and mapped to the newly created + * room. The alias will belong on the *same* homeserver which + * created the room. For example, if this was set to "foo" and + * sent to the homeserver "example.com" the complete room alias + * would be ``#foo:example.com``. + * \param name + * If this is included, an ``m.room.name`` event will be sent + * into the room to indicate the name of the room. See Room + * Events for more information on ``m.room.name``. + * \param topic + * If this is included, an ``m.room.topic`` event will be sent + * into the room to indicate the topic for the room. See Room + * Events for more information on ``m.room.topic``. + * \param invite + * A list of user IDs to invite to the room. This will tell the + * server to invite everyone in the list to the newly created room. + * \param invite3pid + * A list of objects representing third party IDs to invite into + * the room. + * \param creationContent + * Extra keys to be added to the content of the ``m.room.create``. + * The server will clobber the following keys: ``creator``. Future + * versions of the specification may allow the server to clobber + * other keys. + * \param initialState + * A list of state events to set in the new room. This allows + * the user to override the default state events set in the new + * room. The expected format of the state events are an object + * with type, state_key and content keys set. + * + * Takes precedence over events set by ``preset``, but gets + * overriden by ``name`` and ``topic`` keys. + * \param preset + * Convenience parameter for setting various default state events + * based on a preset. + * \param isDirect + * This flag makes the server set the ``is_direct`` flag on the + * ``m.room.member`` events sent to the users in ``invite`` and + * ``invite_3pid``. See `Direct Messaging`_ for more information. + * \param guestCanJoin + * Allows guests to join the room. See `Guest Access`_ for more information. + */ explicit CreateRoomJob(const QString& visibility = {}, const QString& roomAliasName = {}, const QString& name = {}, const QString& topic = {}, const QStringList& invite = {}, const QVector<Invite3pid>& invite3pid = {}, const QJsonObject& creationContent = {}, const QVector<StateEvent>& initialState = {}, const QString& preset = {}, bool isDirect = false, bool guestCanJoin = false); ~CreateRoomJob() override; // Result properties + /// The created room's ID. const QString& roomId() const; protected: diff --git a/lib/csapi/definitions/client_device.h b/lib/csapi/definitions/client_device.h index 4c09e13c..4ed46a52 100644 --- a/lib/csapi/definitions/client_device.h +++ b/lib/csapi/definitions/client_device.h @@ -13,11 +13,20 @@ namespace QMatrixClient { // Data structures + /// A client device struct Device { + /// Identifier of this device. QString deviceId; + /// Display name set by the user for this device. Absent if no name has been + /// set. QString displayName; + /// The IP address where this device was last seen. (May be a few minutes out + /// of date, for efficiency reasons). QString lastSeenIp; + /// The timestamp (in milliseconds since the unix epoch) when this devices + /// was last seen. (May be a few minutes out of date, for efficiency + /// reasons). Omittable<qint64> lastSeenTs; }; diff --git a/lib/csapi/definitions/device_keys.h b/lib/csapi/definitions/device_keys.h index 895700c1..d74c9259 100644 --- a/lib/csapi/definitions/device_keys.h +++ b/lib/csapi/definitions/device_keys.h @@ -13,12 +13,26 @@ namespace QMatrixClient { // Data structures + /// Device identity keys struct DeviceKeys { + /// The ID of the user the device belongs to. Must match the user ID used + /// when logging in. QString userId; + /// The ID of the device these keys belong to. Must match the device ID used + /// when logging in. QString deviceId; + /// The encryption algorithms supported by this device. QStringList algorithms; + /// Public identity keys. The names of the properties should be in the + /// format ``<algorithm>:<device_id>``. The keys themselves should be + /// encoded as specified by the key algorithm. QHash<QString, QString> keys; + /// Signatures for the device key object. A map from user ID, to a map from + /// ``<algorithm>:<device_id>`` to the signature. + /// + /// The signature is calculated using the process described at `Signing + /// JSON`_. QHash<QString, QHash<QString, QString>> signatures; }; diff --git a/lib/csapi/definitions/event_filter.h b/lib/csapi/definitions/event_filter.h index 407ef7c5..4f5b00f9 100644 --- a/lib/csapi/definitions/event_filter.h +++ b/lib/csapi/definitions/event_filter.h @@ -15,10 +15,15 @@ namespace QMatrixClient struct Filter { + /// The maximum number of events to return. Omittable<int> limit; + /// A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter. QStringList notSenders; + /// A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters. QStringList notTypes; + /// A list of senders IDs to include. If this list is absent then all senders are included. QStringList senders; + /// A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters. QStringList types; }; diff --git a/lib/csapi/definitions/push_condition.h b/lib/csapi/definitions/push_condition.h index 5744b9b8..83f63183 100644 --- a/lib/csapi/definitions/push_condition.h +++ b/lib/csapi/definitions/push_condition.h @@ -15,8 +15,18 @@ namespace QMatrixClient struct PushCondition { QString kind; + /// Required for ``event_match`` conditions. The dot-separated field of the + /// event to match. QString key; + /// Required for ``event_match`` conditions. The glob-style pattern to + /// match against. Patterns with no special glob characters should be + /// treated as having asterisks prepended and appended when testing the + /// condition. QString pattern; + /// Required for ``room_member_count`` conditions. A decimal integer + /// optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + /// rooms where the member count is strictly less than the given number and + /// so forth. If no prefix is present, this parameter defaults to ==. QString is; }; diff --git a/lib/csapi/definitions/push_rule.h b/lib/csapi/definitions/push_rule.h index 74ecf79c..d7f93e41 100644 --- a/lib/csapi/definitions/push_rule.h +++ b/lib/csapi/definitions/push_rule.h @@ -19,11 +19,20 @@ namespace QMatrixClient struct PushRule { + /// The actions to perform when this rule is matched. QVector<QVariant> actions; + /// Whether this is a default rule, or has been set explicitly. bool isDefault; + /// Whether the push rule is enabled or not. bool enabled; + /// The ID of this rule. QString ruleId; + /// The conditions that must hold true for an event in order for a rule to be + /// applied to an event. A rule with no conditions always matches. Only + /// applicable to ``underride`` and ``override`` rules. QVector<PushCondition> conditions; + /// The glob-style pattern to match against. Only applicable to ``content`` + /// rules. QString pattern; }; diff --git a/lib/csapi/definitions/room_event_filter.h b/lib/csapi/definitions/room_event_filter.h index b503ec3a..38b3e50f 100644 --- a/lib/csapi/definitions/room_event_filter.h +++ b/lib/csapi/definitions/room_event_filter.h @@ -16,8 +16,11 @@ namespace QMatrixClient struct RoomEventFilter : Filter { + /// A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter. QStringList notRooms; + /// A list of room IDs to include. If this list is absent then all rooms are included. QStringList rooms; + /// If ``true``, includes only events with a url key in their content. If ``false``, excludes those events. bool containsUrl; }; diff --git a/lib/csapi/definitions/sync_filter.h b/lib/csapi/definitions/sync_filter.h index f7428c0d..c4393596 100644 --- a/lib/csapi/definitions/sync_filter.h +++ b/lib/csapi/definitions/sync_filter.h @@ -15,14 +15,22 @@ namespace QMatrixClient { // Data structures + /// Filters to be applied to room data. struct RoomFilter { + /// A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter. This filter is applied before the filters in ``ephemeral``, ``state``, ``timeline`` or ``account_data`` QStringList notRooms; + /// A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in ``ephemeral``, ``state``, ``timeline`` or ``account_data`` QStringList rooms; + /// The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms. Omittable<RoomEventFilter> ephemeral; + /// Include rooms that the user has left in the sync, default false bool includeLeave; + /// The state events to include for rooms. Omittable<RoomEventFilter> state; + /// The message and state update events to include for rooms. Omittable<RoomEventFilter> timeline; + /// The per user account data to include for rooms. Omittable<RoomEventFilter> accountData; }; @@ -35,10 +43,15 @@ namespace QMatrixClient struct SyncFilter { + /// List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\'. A server may include more fields than were requested. QStringList eventFields; + /// The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'. QString eventFormat; + /// The presence updates to include. Omittable<Filter> presence; + /// The user account data that isn't associated with rooms to include. Omittable<Filter> accountData; + /// Filters to be applied to room data. Omittable<RoomFilter> room; }; diff --git a/lib/csapi/device_management.h b/lib/csapi/device_management.h index f9213d22..978d94d3 100644 --- a/lib/csapi/device_management.h +++ b/lib/csapi/device_management.h @@ -15,14 +15,18 @@ namespace QMatrixClient { // Operations + /// List registered devices for the current user + /// + /// Gets information about all devices for the current user. class GetDevicesJob : public BaseJob { public: explicit GetDevicesJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetDevicesJob. This function can be used when - * a URL for GetDevicesJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetDevicesJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -31,6 +35,7 @@ namespace QMatrixClient // Result properties + /// A list of all registered devices for this user. const QVector<Device>& devices() const; protected: @@ -41,14 +46,22 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Get a single device + /// + /// Gets information on a single device, by device id. class GetDeviceJob : public BaseJob { public: + /*! Get a single device + * \param deviceId + * The device to retrieve. + */ explicit GetDeviceJob(const QString& deviceId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetDeviceJob. This function can be used when - * a URL for GetDeviceJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetDeviceJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& deviceId); @@ -57,6 +70,7 @@ namespace QMatrixClient // Result properties + /// Device information const Device& data() const; protected: @@ -67,21 +81,55 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Update a device + /// + /// Updates the metadata on the given device. class UpdateDeviceJob : public BaseJob { public: + /*! Update a device + * \param deviceId + * The device to update. + * \param displayName + * The new display name for this device. If not given, the + * display name is unchanged. + */ explicit UpdateDeviceJob(const QString& deviceId, const QString& displayName = {}); }; + /// Delete a device + /// + /// This API endpoint uses the `User-Interactive Authentication API`_. + /// + /// Deletes the given device, and invalidates any access token associated with it. class DeleteDeviceJob : public BaseJob { public: + /*! Delete a device + * \param deviceId + * The device to delete. + * \param auth + * Additional authentication information for the + * user-interactive authentication API. + */ explicit DeleteDeviceJob(const QString& deviceId, const QJsonObject& auth = {}); }; + /// Bulk deletion of devices + /// + /// This API endpoint uses the `User-Interactive Authentication API`_. + /// + /// Deletes the given devices, and invalidates any access token associated with them. class DeleteDevicesJob : public BaseJob { public: + /*! Bulk deletion of devices + * \param devices + * The list of device IDs to delete. + * \param auth + * Additional authentication information for the + * user-interactive authentication API. + */ explicit DeleteDevicesJob(const QStringList& devices, const QJsonObject& auth = {}); }; } // namespace QMatrixClient diff --git a/lib/csapi/directory.h b/lib/csapi/directory.h index 1e6b2f46..69069ee0 100644 --- a/lib/csapi/directory.h +++ b/lib/csapi/directory.h @@ -11,20 +11,39 @@ namespace QMatrixClient { // Operations + /// Create a new mapping from room alias to room ID. class SetRoomAliasJob : public BaseJob { public: + /*! Create a new mapping from room alias to room ID. + * \param roomAlias + * The room alias to set. + * \param roomId + * The room ID to set. + */ explicit SetRoomAliasJob(const QString& roomAlias, const QString& roomId = {}); }; + /// Get the room ID corresponding to this room alias. + /// + /// Requests that the server resolve a room alias to a room ID. + /// + /// The server will use the federation API to resolve the alias if the + /// domain part of the alias does not correspond to the server's own + /// domain. class GetRoomIdByAliasJob : public BaseJob { public: + /*! Get the room ID corresponding to this room alias. + * \param roomAlias + * The room alias. + */ explicit GetRoomIdByAliasJob(const QString& roomAlias); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetRoomIdByAliasJob. This function can be used when - * a URL for GetRoomIdByAliasJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetRoomIdByAliasJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomAlias); @@ -33,7 +52,9 @@ namespace QMatrixClient // Result properties + /// The room ID for this room alias. const QString& roomId() const; + /// A list of servers that are aware of this room alias. const QStringList& servers() const; protected: @@ -44,14 +65,24 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Remove a mapping of room alias to room ID. + /// + /// Remove a mapping of room alias to room ID. + /// + /// Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator. class DeleteRoomAliasJob : public BaseJob { public: + /*! Remove a mapping of room alias to room ID. + * \param roomAlias + * The room alias to remove. + */ explicit DeleteRoomAliasJob(const QString& roomAlias); - /** Construct a URL out of baseUrl and usual parameters passed to - * DeleteRoomAliasJob. This function can be used when - * a URL for DeleteRoomAliasJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * DeleteRoomAliasJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomAlias); diff --git a/lib/csapi/event_context.h b/lib/csapi/event_context.h index 22c9cbc3..41ee202c 100644 --- a/lib/csapi/event_context.h +++ b/lib/csapi/event_context.h @@ -13,14 +13,28 @@ namespace QMatrixClient { // Operations + /// Get events and state around the specified event. + /// + /// This API returns a number of events that happened just before and + /// after the specified event. This allows clients to get the context + /// surrounding an event. class GetEventContextJob : public BaseJob { public: + /*! Get events and state around the specified event. + * \param roomId + * The room to get events from. + * \param eventId + * The event to get context around. + * \param limit + * The maximum number of events to return. Default: 10. + */ explicit GetEventContextJob(const QString& roomId, const QString& eventId, Omittable<int> limit = none); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetEventContextJob. This function can be used when - * a URL for GetEventContextJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetEventContextJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId, const QString& eventId, Omittable<int> limit = none); @@ -29,11 +43,19 @@ namespace QMatrixClient // Result properties + /// A token that can be used to paginate backwards with. const QString& begin() const; + /// A token that can be used to paginate forwards with. const QString& end() const; + /// A list of room events that happened just before the + /// requested event, in reverse-chronological order. RoomEvents&& eventsBefore(); + /// Details of the requested event. RoomEventPtr&& event(); + /// A list of room events that happened just after the + /// requested event, in chronological order. RoomEvents&& eventsAfter(); + /// The state of the room at the last event returned. StateEvents&& state(); protected: diff --git a/lib/csapi/filter.h b/lib/csapi/filter.h index 92e9c737..87583a59 100644 --- a/lib/csapi/filter.h +++ b/lib/csapi/filter.h @@ -13,14 +13,28 @@ namespace QMatrixClient { // Operations + /// Upload a new filter. + /// + /// Uploads a new filter definition to the homeserver. + /// Returns a filter ID that may be used in future requests to + /// restrict which events are returned to the client. class DefineFilterJob : public BaseJob { public: + /*! Upload a new filter. + * \param userId + * The id of the user uploading the filter. The access token must be authorized to make requests for this user id. + * \param filter + * Uploads a new filter definition to the homeserver. + * Returns a filter ID that may be used in future requests to + * restrict which events are returned to the client. + */ explicit DefineFilterJob(const QString& userId, const SyncFilter& filter); ~DefineFilterJob() override; // Result properties + /// The ID of the filter that was created. const QString& filterId() const; protected: @@ -31,14 +45,22 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Download a filter class GetFilterJob : public BaseJob { public: + /*! Download a filter + * \param userId + * The user ID to download a filter for. + * \param filterId + * The filter ID to download. + */ explicit GetFilterJob(const QString& userId, const QString& filterId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetFilterJob. This function can be used when - * a URL for GetFilterJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetFilterJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId, const QString& filterId); @@ -47,6 +69,7 @@ namespace QMatrixClient // Result properties + /// "The filter defintion" const SyncFilter& data() const; protected: diff --git a/lib/csapi/inviting.h b/lib/csapi/inviting.h index 4fb15155..41283817 100644 --- a/lib/csapi/inviting.h +++ b/lib/csapi/inviting.h @@ -11,9 +11,35 @@ namespace QMatrixClient { // Operations + /// Invite a user to participate in a particular room. + /// + /// .. _invite-by-user-id-endpoint: + /// + /// *Note that there are two forms of this API, which are documented separately. + /// This version of the API requires that the inviter knows the Matrix + /// identifier of the invitee. The other is documented in the* + /// `third party invites section`_. + /// + /// This API invites a user to participate in a particular room. + /// They do not start participating in the room until they actually join the + /// room. + /// + /// Only users currently in a particular room can invite other users to + /// join that room. + /// + /// If the user was invited to the room, the homeserver will append a + /// ``m.room.member`` event to the room. + /// + /// .. _third party invites section: `invite-by-third-party-id-endpoint`_ class InviteUserJob : public BaseJob { public: + /*! Invite a user to participate in a particular room. + * \param roomId + * The room identifier (not alias) to which to invite the user. + * \param userId + * The fully qualified user ID of the invitee. + */ explicit InviteUserJob(const QString& roomId, const QString& userId); }; } // namespace QMatrixClient diff --git a/lib/csapi/joining.h b/lib/csapi/joining.h index 7164f9ff..67dce4c9 100644 --- a/lib/csapi/joining.h +++ b/lib/csapi/joining.h @@ -13,26 +13,53 @@ namespace QMatrixClient { // Operations + /// Start the requesting user participating in a particular room. + /// + /// *Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.* + /// + /// This API starts a user participating in a particular room, if that user + /// is allowed to participate in that room. After this call, the client is + /// allowed to see all current state events in the room, and all subsequent + /// events associated with the room until the user leaves the room. + /// + /// After a user has joined a room, the room will appear as an entry in the + /// response of the |/initialSync|_ and |/sync|_ APIs. + /// + /// If a ``third_party_signed`` was supplied, the homeserver must verify + /// that it matches a pending ``m.room.third_party_invite`` event in the + /// room, and perform key validity checking if required by the event. class JoinRoomByIdJob : public BaseJob { public: // Inner data structures + /// A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room. struct ThirdPartySigned { + /// The Matrix ID of the user who issued the invite. QString sender; + /// The Matrix ID of the invitee. QString mxid; + /// The state key of the m.third_party_invite event. QString token; + /// A signatures object containing a signature of the entire signed object. QJsonObject signatures; }; // Construction/destruction + /*! Start the requesting user participating in a particular room. + * \param roomId + * The room identifier (not alias) to join. + * \param thirdPartySigned + * A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room. + */ explicit JoinRoomByIdJob(const QString& roomId, const Omittable<ThirdPartySigned>& thirdPartySigned = none); ~JoinRoomByIdJob() override; // Result properties + /// The joined room id const QString& roomId() const; protected: @@ -43,31 +70,75 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Start the requesting user participating in a particular room. + /// + /// *Note that this API takes either a room ID or alias, unlike* ``/room/{roomId}/join``. + /// + /// This API starts a user participating in a particular room, if that user + /// is allowed to participate in that room. After this call, the client is + /// allowed to see all current state events in the room, and all subsequent + /// events associated with the room until the user leaves the room. + /// + /// After a user has joined a room, the room will appear as an entry in the + /// response of the |/initialSync|_ and |/sync|_ APIs. + /// + /// If a ``third_party_signed`` was supplied, the homeserver must verify + /// that it matches a pending ``m.room.third_party_invite`` event in the + /// room, and perform key validity checking if required by the event. class JoinRoomJob : public BaseJob { public: // Inner data structures + /// *Note that this API takes either a room ID or alias, unlike* ``/room/{roomId}/join``. + /// + /// This API starts a user participating in a particular room, if that user + /// is allowed to participate in that room. After this call, the client is + /// allowed to see all current state events in the room, and all subsequent + /// events associated with the room until the user leaves the room. + /// + /// After a user has joined a room, the room will appear as an entry in the + /// response of the |/initialSync|_ and |/sync|_ APIs. + /// + /// If a ``third_party_signed`` was supplied, the homeserver must verify + /// that it matches a pending ``m.room.third_party_invite`` event in the + /// room, and perform key validity checking if required by the event. struct Signed { + /// The Matrix ID of the user who issued the invite. QString sender; + /// The Matrix ID of the invitee. QString mxid; + /// The state key of the m.third_party_invite event. QString token; + /// A signatures object containing a signature of the entire signed object. QJsonObject signatures; }; + /// A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room. struct ThirdPartySigned { + /// A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room. Signed signedData; }; // Construction/destruction + /*! Start the requesting user participating in a particular room. + * \param roomIdOrAlias + * The room identifier or alias to join. + * \param serverName + * The servers to attempt to join the room through. One of the servers + * must be participating in the room. + * \param thirdPartySigned + * A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room. + */ explicit JoinRoomJob(const QString& roomIdOrAlias, const QStringList& serverName = {}, const Omittable<ThirdPartySigned>& thirdPartySigned = none); ~JoinRoomJob() override; // Result properties + /// The joined room id const QString& roomId() const; protected: diff --git a/lib/csapi/keys.h b/lib/csapi/keys.h index d4b0f62f..1384faf8 100644 --- a/lib/csapi/keys.h +++ b/lib/csapi/keys.h @@ -16,14 +16,31 @@ namespace QMatrixClient { // Operations + /// Upload end-to-end encryption keys. + /// + /// Publishes end-to-end encryption keys for the device. class UploadKeysJob : public BaseJob { public: + /*! Upload end-to-end encryption keys. + * \param deviceKeys + * Identity keys for the device. May be absent if no new + * identity keys are required. + * \param oneTimeKeys + * One-time public keys for "pre-key" messages. The names of + * the properties should be in the format + * ``<algorithm>:<key_id>``. The format of the key is determined + * by the key algorithm. + * + * May be absent if no new one-time keys are required. + */ explicit UploadKeysJob(const Omittable<DeviceKeys>& deviceKeys = none, const QHash<QString, QVariant>& oneTimeKeys = {}); ~UploadKeysJob() override; // Result properties + /// For each key algorithm, the number of unclaimed one-time keys + /// of that type currently held on the server for this device. const QHash<QString, int>& oneTimeKeyCounts() const; protected: @@ -34,29 +51,66 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Download device identity keys. + /// + /// Returns the current devices and identity keys for the given users. class QueryKeysJob : public BaseJob { public: // Inner data structures + /// Additional data added to the device key information + /// by intermediate servers, and not covered by the + /// signatures. struct UnsignedDeviceInfo { + /// The display name which the user set on the device. QString deviceDisplayName; }; + /// Returns the current devices and identity keys for the given users. struct DeviceInformation : DeviceKeys { + /// Additional data added to the device key information + /// by intermediate servers, and not covered by the + /// signatures. Omittable<UnsignedDeviceInfo> unsignedData; }; // Construction/destruction + /*! Download device identity keys. + * \param deviceKeys + * The keys to be downloaded. A map from user ID, to a list of + * device IDs, or to an empty list to indicate all devices for the + * corresponding user. + * \param timeout + * The time (in milliseconds) to wait when downloading keys from + * remote servers. 10 seconds is the recommended default. + * \param token + * If the client is fetching keys as a result of a device update received + * in a sync request, this should be the 'since' token of that sync request, + * or any later sync token. This allows the server to ensure its response + * contains the keys advertised by the notification in that sync. + */ explicit QueryKeysJob(const QHash<QString, QStringList>& deviceKeys, Omittable<int> timeout = none, const QString& token = {}); ~QueryKeysJob() override; // Result properties + /// If any remote homeservers could not be reached, they are + /// recorded here. The names of the properties are the names of + /// the unreachable servers. + /// + /// If the homeserver could be reached, but the user or device + /// was unknown, no failure is recorded. Instead, the corresponding + /// user or device is missing from the ``device_keys`` result. const QHash<QString, QJsonObject>& failures() const; + /// Information on the queried devices. A map from user ID, to a + /// map from device ID to device information. For each device, + /// the information returned will be the same as uploaded via + /// ``/keys/upload``, with the addition of an ``unsigned`` + /// property. const QHash<QString, QHash<QString, DeviceInformation>>& deviceKeys() const; protected: @@ -67,15 +121,35 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Claim one-time encryption keys. + /// + /// Claims one-time keys for use in pre-key messages. class ClaimKeysJob : public BaseJob { public: + /*! Claim one-time encryption keys. + * \param oneTimeKeys + * The keys to be claimed. A map from user ID, to a map from + * device ID to algorithm name. + * \param timeout + * The time (in milliseconds) to wait when downloading keys from + * remote servers. 10 seconds is the recommended default. + */ explicit ClaimKeysJob(const QHash<QString, QHash<QString, QString>>& oneTimeKeys, Omittable<int> timeout = none); ~ClaimKeysJob() override; // Result properties + /// If any remote homeservers could not be reached, they are + /// recorded here. The names of the properties are the names of + /// the unreachable servers. + /// + /// If the homeserver could be reached, but the user or device + /// was unknown, no failure is recorded. Instead, the corresponding + /// user or device is missing from the ``one_time_keys`` result. const QHash<QString, QJsonObject>& failures() const; + /// One-time keys for the queried devices. A map from user ID, to a + /// map from devices to a map from ``<algorithm>:<key_id>`` to the key object. const QHash<QString, QHash<QString, QVariant>>& oneTimeKeys() const; protected: @@ -86,14 +160,39 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Query users with recent device key updates. + /// + /// Gets a list of users who have updated their device identity keys since a + /// previous sync token. + /// + /// The server should include in the results any users who: + /// + /// * currently share a room with the calling user (ie, both users have + /// membership state ``join``); *and* + /// * added new device identity keys or removed an existing device with + /// identity keys, between ``from`` and ``to``. class GetKeysChangesJob : public BaseJob { public: + /*! Query users with recent device key updates. + * \param from + * The desired start point of the list. Should be the ``next_batch`` field + * from a response to an earlier call to |/sync|. Users who have not + * uploaded new device identity keys since this point, nor deleted + * existing devices with identity keys since then, will be excluded + * from the results. + * \param to + * The desired end point of the list. Should be the ``next_batch`` + * field from a recent call to |/sync| - typically the most recent + * such call. This may be used by the server as a hint to check its + * caches are up to date. + */ explicit GetKeysChangesJob(const QString& from, const QString& to); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetKeysChangesJob. This function can be used when - * a URL for GetKeysChangesJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetKeysChangesJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& from, const QString& to); @@ -102,7 +201,12 @@ namespace QMatrixClient // Result properties + /// The Matrix User IDs of all users who updated their device + /// identity keys. const QStringList& changed() const; + /// The Matrix User IDs of all users who may have left all + /// the end-to-end encrypted rooms they previously shared + /// with the user. const QStringList& left() const; protected: diff --git a/lib/csapi/kicking.h b/lib/csapi/kicking.h index 2a2d44b1..dde373b1 100644 --- a/lib/csapi/kicking.h +++ b/lib/csapi/kicking.h @@ -11,9 +11,27 @@ namespace QMatrixClient { // Operations + /// Kick a user from the room. + /// + /// Kick a user from the room. + /// + /// The caller must have the required power level in order to perform this operation. + /// + /// Kicking a user adjusts the target member's membership state to be ``leave`` with an + /// optional ``reason``. Like with other membership changes, a user can directly adjust + /// the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``. class KickJob : public BaseJob { public: + /*! Kick a user from the room. + * \param roomId + * The room identifier (not alias) from which the user should be kicked. + * \param userId + * The fully qualified user ID of the user being kicked. + * \param reason + * The reason the user has been kicked. This will be supplied as the + * ``reason`` on the target's updated `m.room.member`_ event. + */ explicit KickJob(const QString& roomId, const QString& userId, const QString& reason = {}); }; } // namespace QMatrixClient diff --git a/lib/csapi/leaving.h b/lib/csapi/leaving.h index d571367b..95859627 100644 --- a/lib/csapi/leaving.h +++ b/lib/csapi/leaving.h @@ -11,28 +11,62 @@ namespace QMatrixClient { // Operations + /// Stop the requesting user participating in a particular room. + /// + /// This API stops a user participating in a particular room. + /// + /// If the user was already in the room, they will no longer be able to see + /// new events in the room. If the room requires an invite to join, they + /// will need to be re-invited before they can re-join. + /// + /// If the user was invited to the room, but had not joined, this call + /// serves to reject the invite. + /// + /// The user will still be allowed to retrieve history from the room which + /// they were previously allowed to see. class LeaveRoomJob : public BaseJob { public: + /*! Stop the requesting user participating in a particular room. + * \param roomId + * The room identifier to leave. + */ explicit LeaveRoomJob(const QString& roomId); - /** Construct a URL out of baseUrl and usual parameters passed to - * LeaveRoomJob. This function can be used when - * a URL for LeaveRoomJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * LeaveRoomJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId); }; + /// Stop the requesting user remembering about a particular room. + /// + /// This API stops a user remembering about a particular room. + /// + /// In general, history is a first class citizen in Matrix. After this API + /// is called, however, a user will no longer be able to retrieve history + /// for this room. If all users on a homeserver forget a room, the room is + /// eligible for deletion from that homeserver. + /// + /// If the user is currently joined to the room, they must leave the room + /// before calling this API. class ForgetRoomJob : public BaseJob { public: + /*! Stop the requesting user remembering about a particular room. + * \param roomId + * The room identifier to forget. + */ explicit ForgetRoomJob(const QString& roomId); - /** Construct a URL out of baseUrl and usual parameters passed to - * ForgetRoomJob. This function can be used when - * a URL for ForgetRoomJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * ForgetRoomJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId); diff --git a/lib/csapi/list_joined_rooms.h b/lib/csapi/list_joined_rooms.h index 2a030a54..2032265c 100644 --- a/lib/csapi/list_joined_rooms.h +++ b/lib/csapi/list_joined_rooms.h @@ -11,14 +11,18 @@ namespace QMatrixClient { // Operations + /// Lists the user's current rooms. + /// + /// This API returns a list of the user's current rooms. class GetJoinedRoomsJob : public BaseJob { public: explicit GetJoinedRoomsJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetJoinedRoomsJob. This function can be used when - * a URL for GetJoinedRoomsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetJoinedRoomsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -27,6 +31,7 @@ namespace QMatrixClient // Result properties + /// The ID of each room in which the user has ``joined`` membership. const QStringList& joinedRooms() const; protected: diff --git a/lib/csapi/list_public_rooms.h b/lib/csapi/list_public_rooms.h index c12773aa..6e8eb7b3 100644 --- a/lib/csapi/list_public_rooms.h +++ b/lib/csapi/list_public_rooms.h @@ -13,14 +13,22 @@ namespace QMatrixClient { // Operations + /// Gets the visibility of a room in the directory + /// + /// Gets the visibility of a given room on the server's public room directory. class GetRoomVisibilityOnDirectoryJob : public BaseJob { public: + /*! Gets the visibility of a room in the directory + * \param roomId + * The room ID. + */ explicit GetRoomVisibilityOnDirectoryJob(const QString& roomId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetRoomVisibilityOnDirectoryJob. This function can be used when - * a URL for GetRoomVisibilityOnDirectoryJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetRoomVisibilityOnDirectoryJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId); @@ -29,6 +37,7 @@ namespace QMatrixClient // Result properties + /// The visibility of the room in the directory. const QString& visibility() const; protected: @@ -39,37 +48,86 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Sets the visibility of a room in the room directory + /// + /// Sets the visibility of a given room in the server's public room + /// directory. + /// + /// Servers may choose to implement additional access control checks + /// here, for instance that room visibility can only be changed by + /// the room creator or a server administrator. class SetRoomVisibilityOnDirectoryJob : public BaseJob { public: + /*! Sets the visibility of a room in the room directory + * \param roomId + * The room ID. + * \param visibility + * The new visibility setting for the room. + * Defaults to 'public'. + */ explicit SetRoomVisibilityOnDirectoryJob(const QString& roomId, const QString& visibility = {}); }; + /// Lists the public rooms on the server. + /// + /// Lists the public rooms on the server. + /// + /// This API returns paginated responses. The rooms are ordered by the number + /// of joined members, with the largest rooms first. class GetPublicRoomsJob : public BaseJob { public: // Inner data structures + /// Lists the public rooms on the server. + /// + /// This API returns paginated responses. The rooms are ordered by the number + /// of joined members, with the largest rooms first. struct PublicRoomsChunk { + /// Aliases of the room. May be empty. QStringList aliases; + /// The canonical alias of the room, if any. QString canonicalAlias; + /// The name of the room, if any. QString name; + /// The number of members joined to the room. qint64 numJoinedMembers; + /// The ID of the room. QString roomId; + /// The topic of the room, if any. QString topic; + /// Whether the room may be viewed by guest users without joining. bool worldReadable; + /// Whether guest users may join the room and participate in it. + /// If they can, they will be subject to ordinary power level + /// rules like any other user. bool guestCanJoin; + /// The URL for the room's avatar, if one is set. QString avatarUrl; }; // Construction/destruction + /*! Lists the public rooms on the server. + * \param limit + * Limit the number of results returned. + * \param since + * A pagination token from a previous request, allowing clients to + * get the next (or previous) batch of rooms. + * The direction of pagination is specified solely by which token + * is supplied, rather than via an explicit flag. + * \param server + * The server to fetch the public room lists from. Defaults to the + * local server. + */ explicit GetPublicRoomsJob(Omittable<int> limit = none, const QString& since = {}, const QString& server = {}); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetPublicRoomsJob. This function can be used when - * a URL for GetPublicRoomsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetPublicRoomsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, Omittable<int> limit = none, const QString& since = {}, const QString& server = {}); @@ -78,9 +136,18 @@ namespace QMatrixClient // Result properties + /// A paginated chunk of public rooms. const QVector<PublicRoomsChunk>& chunk() const; + /// A pagination token for the response. The absence of this token + /// means there are no more results to fetch and the client should + /// stop paginating. const QString& nextBatch() const; + /// A pagination token that allows fetching previous results. The + /// absence of this token means there are no results before this + /// batch, i.e. this is the first batch. const QString& prevBatch() const; + /// An estimate on the total number of public rooms, if the + /// server has an estimate. Omittable<qint64> totalRoomCountEstimate() const; protected: @@ -91,39 +158,86 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Lists the public rooms on the server with optional filter. + /// + /// Lists the public rooms on the server, with optional filter. + /// + /// This API returns paginated responses. The rooms are ordered by the number + /// of joined members, with the largest rooms first. class QueryPublicRoomsJob : public BaseJob { public: // Inner data structures + /// Filter to apply to the results. struct Filter { + /// A string to search for in the room metadata, e.g. name, + /// topic, canonical alias etc. (Optional). QString genericSearchTerm; }; + /// Lists the public rooms on the server, with optional filter. + /// + /// This API returns paginated responses. The rooms are ordered by the number + /// of joined members, with the largest rooms first. struct PublicRoomsChunk { + /// Aliases of the room. May be empty. QStringList aliases; + /// The canonical alias of the room, if any. QString canonicalAlias; + /// The name of the room, if any. QString name; + /// The number of members joined to the room. qint64 numJoinedMembers; + /// The ID of the room. QString roomId; + /// The topic of the room, if any. QString topic; + /// Whether the room may be viewed by guest users without joining. bool worldReadable; + /// Whether guest users may join the room and participate in it. + /// If they can, they will be subject to ordinary power level + /// rules like any other user. bool guestCanJoin; + /// The URL for the room's avatar, if one is set. QString avatarUrl; }; // Construction/destruction + /*! Lists the public rooms on the server with optional filter. + * \param server + * The server to fetch the public room lists from. Defaults to the + * local server. + * \param limit + * Limit the number of results returned. + * \param since + * A pagination token from a previous request, allowing clients + * to get the next (or previous) batch of rooms. The direction + * of pagination is specified solely by which token is supplied, + * rather than via an explicit flag. + * \param filter + * Filter to apply to the results. + */ explicit QueryPublicRoomsJob(const QString& server = {}, Omittable<int> limit = none, const QString& since = {}, const Omittable<Filter>& filter = none); ~QueryPublicRoomsJob() override; // Result properties + /// A paginated chunk of public rooms. const QVector<PublicRoomsChunk>& chunk() const; + /// A pagination token for the response. The absence of this token + /// means there are no more results to fetch and the client should + /// stop paginating. const QString& nextBatch() const; + /// A pagination token that allows fetching previous results. The + /// absence of this token means there are no results before this + /// batch, i.e. this is the first batch. const QString& prevBatch() const; + /// An estimate on the total number of public rooms, if the + /// server has an estimate. Omittable<qint64> totalRoomCountEstimate() const; protected: diff --git a/lib/csapi/login.h b/lib/csapi/login.h index 6e462aeb..31d4dc64 100644 --- a/lib/csapi/login.h +++ b/lib/csapi/login.h @@ -13,13 +13,21 @@ namespace QMatrixClient { // Operations + /// Get the supported login types to authenticate users + /// + /// Gets the homeserver's supported login types to authenticate users. Clients + /// should pick one of these and supply it as the ``type`` when logging in. class GetLoginFlowsJob : public BaseJob { public: // Inner data structures + /// Gets the homeserver's supported login types to authenticate users. Clients + /// should pick one of these and supply it as the ``type`` when logging in. struct LoginFlow { + /// The login type. This is supplied as the ``type`` when + /// logging in. QString type; }; @@ -27,9 +35,10 @@ namespace QMatrixClient explicit GetLoginFlowsJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetLoginFlowsJob. This function can be used when - * a URL for GetLoginFlowsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetLoginFlowsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -38,6 +47,7 @@ namespace QMatrixClient // Result properties + /// The homeserver's supported login types const QVector<LoginFlow>& flows() const; protected: @@ -48,17 +58,62 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Authenticates the user. + /// + /// Authenticates the user, and issues an access token they can + /// use to authorize themself in subsequent requests. + /// + /// If the client does not supply a ``device_id``, the server must + /// auto-generate one. + /// + /// 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 LoginJob : public BaseJob { public: + /*! Authenticates the user. + * \param type + * The login type being used. + * \param user + * The fully qualified user ID or just local part of the user ID, to log in. + * \param medium + * When logging in using a third party identifier, the medium of the identifier. Must be 'email'. + * \param address + * Third party identifier for the user. + * \param password + * Required when ``type`` is ``m.login.password``. The user's + * password. + * \param token + * Required when ``type`` is ``m.login.token``. Part of `Token-based`_ login. + * \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 LoginJob(const QString& type, const QString& user = {}, const QString& medium = {}, const QString& address = {}, const QString& password = {}, const QString& token = {}, const QString& deviceId = {}, const QString& initialDeviceDisplayName = {}); ~LoginJob() override; // Result properties + /// The fully-qualified Matrix ID that has been registered. 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 logged-in device. Will be the same as the + /// corresponding parameter in the request, if one was specified. const QString& deviceId() const; protected: diff --git a/lib/csapi/logout.h b/lib/csapi/logout.h index 7862c930..f124ac68 100644 --- a/lib/csapi/logout.h +++ b/lib/csapi/logout.h @@ -11,28 +11,44 @@ namespace QMatrixClient { // Operations + /// Invalidates a user access token + /// + /// Invalidates an existing access token, so that it can no longer be used for + /// authorization. class LogoutJob : public BaseJob { public: explicit LogoutJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * LogoutJob. This function can be used when - * a URL for LogoutJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * LogoutJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); }; + /// Invalidates all access tokens for a user + /// + /// Invalidates all access tokens for a user, so that they can no longer be used for + /// authorization. This includes the access token that made this request. + /// + /// This endpoint does not require UI authorization because UI authorization is + /// designed to protect against attacks where the someone gets hold of a single access + /// token then takes over the account. This endpoint invalidates all access tokens for + /// the user, including the token used in the request, and therefore the attacker is + /// unable to take over the account in this way. class LogoutAllJob : public BaseJob { public: explicit LogoutAllJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * LogoutAllJob. This function can be used when - * a URL for LogoutAllJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * LogoutAllJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); diff --git a/lib/csapi/message_pagination.h b/lib/csapi/message_pagination.h index 58900940..890f3ac8 100644 --- a/lib/csapi/message_pagination.h +++ b/lib/csapi/message_pagination.h @@ -13,14 +13,39 @@ namespace QMatrixClient { // Operations + /// Get a list of events for this room + /// + /// This API returns a list of message and state events for a room. It uses + /// pagination query parameters to paginate history in the room. class GetRoomEventsJob : public BaseJob { public: + /*! Get a list of events for this room + * \param roomId + * The room to get events from. + * \param from + * The token to start returning events from. This token can be obtained + * from a ``prev_batch`` token returned for each room by the sync API, + * or from a ``start`` or ``end`` token returned by a previous request + * to this endpoint. + * \param dir + * The direction to return events from. + * \param to + * The token to stop returning events at. This token can be obtained from + * a ``prev_batch`` token returned for each room by the sync endpoint, + * or from a ``start`` or ``end`` token returned by a previous request to + * this endpoint. + * \param limit + * The maximum number of events to return. Default: 10. + * \param filter + * A JSON RoomEventFilter to filter returned events with. + */ explicit GetRoomEventsJob(const QString& roomId, const QString& from, const QString& dir, const QString& to = {}, Omittable<int> limit = none, const QString& filter = {}); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetRoomEventsJob. This function can be used when - * a URL for GetRoomEventsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetRoomEventsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId, const QString& from, const QString& dir, const QString& to = {}, Omittable<int> limit = none, const QString& filter = {}); @@ -29,8 +54,13 @@ namespace QMatrixClient // Result properties + /// The token the pagination starts from. If ``dir=b`` this will be + /// the token supplied in ``from``. const QString& begin() const; + /// The token the pagination ends at. If ``dir=b`` this token should + /// be used again to request even earlier events. const QString& end() const; + /// A list of room events. RoomEvents&& chunk(); protected: diff --git a/lib/csapi/notifications.h b/lib/csapi/notifications.h index 3698431d..25db7052 100644 --- a/lib/csapi/notifications.h +++ b/lib/csapi/notifications.h @@ -16,28 +16,54 @@ namespace QMatrixClient { // Operations + /// Gets a list of events that the user has been notified about + /// + /// This API is used to paginate through the list of events that the + /// user has been, or would have been notified about. class GetNotificationsJob : public BaseJob { public: // Inner data structures + /// This API is used to paginate through the list of events that the + /// user has been, or would have been notified about. struct Notification { + /// The action(s) to perform when the conditions for this rule are met. + /// See `Push Rules: API`_. QVector<QVariant> actions; + /// The Event object for the event that triggered the notification. EventPtr event; + /// The profile tag of the rule that matched this event. QString profileTag; + /// Indicates whether the user has sent a read receipt indicating + /// that they have read this message. bool read; + /// The ID of the room in which the event was posted. QString roomId; + /// The unix timestamp at which the event notification was sent, + /// in milliseconds. qint64 ts; }; // Construction/destruction + /*! Gets a list of events that the user has been notified about + * \param from + * Pagination token given to retrieve the next set of events. + * \param limit + * Limit on the number of events to return in this request. + * \param only + * Allows basic filtering of events returned. Supply ``highlight`` + * to return only events where the notification had the highlight + * tweak set. + */ explicit GetNotificationsJob(const QString& from = {}, Omittable<int> limit = none, const QString& only = {}); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetNotificationsJob. This function can be used when - * a URL for GetNotificationsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetNotificationsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& from = {}, Omittable<int> limit = none, const QString& only = {}); @@ -46,7 +72,11 @@ namespace QMatrixClient // Result properties + /// The token to supply in the ``from`` param of the next + /// ``/notifications`` request in order to request more + /// events. If this is absent, there are no more results. const QString& nextToken() const; + /// The list of events that triggered notifications. std::vector<Notification>&& notifications(); protected: diff --git a/lib/csapi/peeking_events.h b/lib/csapi/peeking_events.h index 5f2c4233..f8e8b966 100644 --- a/lib/csapi/peeking_events.h +++ b/lib/csapi/peeking_events.h @@ -13,14 +13,36 @@ namespace QMatrixClient { // Operations + /// Listen on the event stream. + /// + /// This will listen for new events related to a particular room and return + /// them to the caller. This will block until an event is received, or until + /// the ``timeout`` is reached. + /// + /// This API is the same as the normal ``/events`` endpoint, but can be + /// called by users who have not joined the room. + /// + /// Note that the normal ``/events`` endpoint has been deprecated. This + /// API will also be deprecated at some point, but its replacement is not + /// yet known. class PeekEventsJob : public BaseJob { public: + /*! Listen on the event stream. + * \param from + * The token to stream from. This token is either from a previous + * request to this API or from the initial sync API. + * \param timeout + * The maximum time in milliseconds to wait for an event. + * \param roomId + * The room ID for which events should be returned. + */ explicit PeekEventsJob(const QString& from = {}, Omittable<int> timeout = none, const QString& roomId = {}); - /** Construct a URL out of baseUrl and usual parameters passed to - * PeekEventsJob. This function can be used when - * a URL for PeekEventsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * PeekEventsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& from = {}, Omittable<int> timeout = none, const QString& roomId = {}); @@ -29,8 +51,13 @@ namespace QMatrixClient // Result properties + /// A token which correlates to the first value in ``chunk``. This + /// is usually the same token supplied to ``from=``. const QString& begin() const; + /// A token which correlates to the last value in ``chunk``. This + /// token should be used in the next request to ``/events``. const QString& end() const; + /// An array of events. RoomEvents&& chunk(); protected: diff --git a/lib/csapi/presence.h b/lib/csapi/presence.h index 7d6665f3..74380ed1 100644 --- a/lib/csapi/presence.h +++ b/lib/csapi/presence.h @@ -13,20 +13,42 @@ namespace QMatrixClient { // Operations + /// Update this user's presence state. + /// + /// This API sets the given user's presence state. When setting the status, + /// the activity time is updated to reflect that activity; the client does + /// not need to specify the ``last_active_ago`` field. You cannot set the + /// presence state of another user. class SetPresenceJob : public BaseJob { public: + /*! Update this user's presence state. + * \param userId + * The user whose presence state to update. + * \param presence + * The new presence state. + * \param statusMsg + * The status message to attach to this state. + */ explicit SetPresenceJob(const QString& userId, const QString& presence, const QString& statusMsg = {}); }; + /// Get this user's presence state. + /// + /// Get the given user's presence state. class GetPresenceJob : public BaseJob { public: + /*! Get this user's presence state. + * \param userId + * The user whose presence state to get. + */ explicit GetPresenceJob(const QString& userId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetPresenceJob. This function can be used when - * a URL for GetPresenceJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetPresenceJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId); @@ -35,9 +57,14 @@ namespace QMatrixClient // Result properties + /// This user's presence. const QString& presence() const; + /// The length of time in milliseconds since an action was performed + /// by this user. Omittable<int> lastActiveAgo() const; + /// The state message for this user if one was set. const QString& statusMsg() const; + /// Whether the user is currently active bool currentlyActive() const; protected: @@ -48,20 +75,39 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Add or remove users from this presence list. + /// + /// Adds or removes users from this presence list. class ModifyPresenceListJob : public BaseJob { public: + /*! Add or remove users from this presence list. + * \param userId + * The user whose presence list is being modified. + * \param invite + * A list of user IDs to add to the list. + * \param drop + * A list of user IDs to remove from the list. + */ explicit ModifyPresenceListJob(const QString& userId, const QStringList& invite = {}, const QStringList& drop = {}); }; + /// Get presence events for this presence list. + /// + /// Retrieve a list of presence events for every user on this list. class GetPresenceForListJob : public BaseJob { public: + /*! Get presence events for this presence list. + * \param userId + * The user whose presence list should be retrieved. + */ explicit GetPresenceForListJob(const QString& userId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetPresenceForListJob. This function can be used when - * a URL for GetPresenceForListJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetPresenceForListJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId); @@ -70,6 +116,7 @@ namespace QMatrixClient // Result properties + /// A list of presence events for this list. Events&& data(); protected: diff --git a/lib/csapi/profile.h b/lib/csapi/profile.h index 77eebdfa..694f36b8 100644 --- a/lib/csapi/profile.h +++ b/lib/csapi/profile.h @@ -11,20 +11,40 @@ namespace QMatrixClient { // Operations + /// Set the user's display name. + /// + /// This API sets the given user's display name. You must have permission to + /// set this user's display name, e.g. you need to have their ``access_token``. class SetDisplayNameJob : public BaseJob { public: + /*! Set the user's display name. + * \param userId + * The user whose display name to set. + * \param displayname + * The new display name for this user. + */ explicit SetDisplayNameJob(const QString& userId, const QString& displayname = {}); }; + /// Get the user's display name. + /// + /// Get the user's display name. This API may be used to fetch the user's + /// own displayname or to query the name of other users; either locally or + /// on remote homeservers. class GetDisplayNameJob : public BaseJob { public: + /*! Get the user's display name. + * \param userId + * The user whose display name to get. + */ explicit GetDisplayNameJob(const QString& userId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetDisplayNameJob. This function can be used when - * a URL for GetDisplayNameJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetDisplayNameJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId); @@ -33,6 +53,7 @@ namespace QMatrixClient // Result properties + /// The user's display name if they have set one, otherwise not present. const QString& displayname() const; protected: @@ -43,20 +64,40 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Set the user's avatar URL. + /// + /// This API sets the given user's avatar URL. You must have permission to + /// set this user's avatar URL, e.g. you need to have their ``access_token``. class SetAvatarUrlJob : public BaseJob { public: + /*! Set the user's avatar URL. + * \param userId + * The user whose avatar URL to set. + * \param avatarUrl + * The new avatar URL for this user. + */ explicit SetAvatarUrlJob(const QString& userId, const QString& avatarUrl = {}); }; + /// Get the user's avatar URL. + /// + /// Get the user's avatar URL. This API may be used to fetch the user's + /// own avatar URL or to query the URL of other users; either locally or + /// on remote homeservers. class GetAvatarUrlJob : public BaseJob { public: + /*! Get the user's avatar URL. + * \param userId + * The user whose avatar URL to get. + */ explicit GetAvatarUrlJob(const QString& userId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetAvatarUrlJob. This function can be used when - * a URL for GetAvatarUrlJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetAvatarUrlJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId); @@ -65,6 +106,7 @@ namespace QMatrixClient // Result properties + /// The user's avatar URL if they have set one, otherwise not present. const QString& avatarUrl() const; protected: @@ -75,14 +117,25 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Get this user's profile information. + /// + /// Get the combined profile information for this user. This API may be used + /// to fetch the user's own profile information or other users; either + /// locally or on remote homeservers. This API may return keys which are not + /// limited to ``displayname`` or ``avatar_url``. class GetUserProfileJob : public BaseJob { public: + /*! Get this user's profile information. + * \param userId + * The user whose profile information to get. + */ explicit GetUserProfileJob(const QString& userId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetUserProfileJob. This function can be used when - * a URL for GetUserProfileJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetUserProfileJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId); @@ -91,7 +144,9 @@ namespace QMatrixClient // Result properties + /// The user's avatar URL if they have set one, otherwise not present. const QString& avatarUrl() const; + /// The user's display name if they have set one, otherwise not present. const QString& displayname() const; protected: diff --git a/lib/csapi/pusher.h b/lib/csapi/pusher.h index bfea57d1..34423dde 100644 --- a/lib/csapi/pusher.h +++ b/lib/csapi/pusher.h @@ -13,25 +13,50 @@ namespace QMatrixClient { // Operations + /// Gets the current pushers for the authenticated user + /// + /// Gets all currently active pushers for the authenticated user class GetPushersJob : public BaseJob { public: // Inner data structures + /// A dictionary of information for the pusher implementation + /// itself. struct PusherData { + /// Required if ``kind`` is ``http``. The URL to use to send + /// notifications to. QString url; }; + /// Gets all currently active pushers for the authenticated user struct Pusher { + /// This is a unique identifier for this pusher. See `/set` for + /// more detail. + /// Max length, 512 bytes. QString pushkey; + /// The kind of pusher. ``"http"`` is a pusher that + /// sends HTTP pokes. QString kind; + /// This is a reverse-DNS style identifier for the application. + /// Max length, 64 chars. QString appId; + /// A string that will allow the user to identify what application + /// owns this pusher. QString appDisplayName; + /// A string that will allow the user to identify what device owns + /// this pusher. QString deviceDisplayName; + /// This string determines which set of device specific rules this + /// pusher executes. QString profileTag; + /// The preferred language for receiving notifications (e.g. 'en' + /// or 'en-US') QString lang; + /// A dictionary of information for the pusher implementation + /// itself. Omittable<PusherData> data; }; @@ -39,9 +64,10 @@ namespace QMatrixClient explicit GetPushersJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetPushersJob. This function can be used when - * a URL for GetPushersJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetPushersJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -50,6 +76,7 @@ namespace QMatrixClient // Result properties + /// An array containing the current pushers for the user const QVector<Pusher>& pushers() const; protected: @@ -60,18 +87,67 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Modify a pusher for this user on the homeserver. + /// + /// This endpoint allows the creation, modification and deletion of `pushers`_ + /// for this user ID. The behaviour of this endpoint varies depending on the + /// values in the JSON body. class PostPusherJob : public BaseJob { public: // Inner data structures + /// A dictionary of information for the pusher implementation + /// itself. If ``kind`` is ``http``, this should contain ``url`` + /// which is the URL to use to send notifications to. struct PusherData { + /// Required if ``kind`` is ``http``. The URL to use to send + /// notifications to. QString url; }; // Construction/destruction + /*! Modify a pusher for this user on the homeserver. + * \param pushkey + * This is a unique identifier for this pusher. The value you + * should use for this is the routing or destination address + * information for the notification, for example, the APNS token + * for APNS or the Registration ID for GCM. If your notification + * client has no such concept, use any unique identifier. + * Max length, 512 bytes. + * \param kind + * The kind of pusher to configure. ``"http"`` makes a pusher that + * sends HTTP pokes. ``null`` deletes the pusher. + * \param appId + * This is a reverse-DNS style identifier for the application. + * It is recommended that this end with the platform, such that + * different platform versions get different app identifiers. + * Max length, 64 chars. + * \param appDisplayName + * A string that will allow the user to identify what application + * owns this pusher. + * \param deviceDisplayName + * A string that will allow the user to identify what device owns + * this pusher. + * \param lang + * The preferred language for receiving notifications (e.g. 'en' + * or 'en-US') + * \param data + * A dictionary of information for the pusher implementation + * itself. If ``kind`` is ``http``, this should contain ``url`` + * which is the URL to use to send notifications to. + * \param profileTag + * This string determines which set of device specific rules this + * pusher executes. + * \param append + * If true, the homeserver should add another pusher with the + * given pushkey and App ID in addition to any others with + * different user IDs. Otherwise, the homeserver must remove any + * other pushers with the same App ID and pushkey for different + * users. The default is ``false``. + */ explicit PostPusherJob(const QString& pushkey, const QString& kind, const QString& appId, const QString& appDisplayName, const QString& deviceDisplayName, const QString& lang, const PusherData& data, const QString& profileTag = {}, bool append = false); }; } // namespace QMatrixClient diff --git a/lib/csapi/pushrules.h b/lib/csapi/pushrules.h index b5950e0c..1f847013 100644 --- a/lib/csapi/pushrules.h +++ b/lib/csapi/pushrules.h @@ -16,14 +16,21 @@ namespace QMatrixClient { // Operations + /// Retrieve all push rulesets. + /// + /// Retrieve all push rulesets for this user. Clients can "drill-down" on + /// the rulesets by suffixing a ``scope`` to this path e.g. + /// ``/pushrules/global/``. This will return a subset of this data under the + /// specified key e.g. the ``global`` key. class GetPushRulesJob : public BaseJob { public: explicit GetPushRulesJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetPushRulesJob. This function can be used when - * a URL for GetPushRulesJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetPushRulesJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -32,6 +39,7 @@ namespace QMatrixClient // Result properties + /// The global ruleset. const PushRuleset& global() const; protected: @@ -42,14 +50,26 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Retrieve a push rule. + /// + /// Retrieve a single specified push rule. class GetPushRuleJob : public BaseJob { public: + /*! Retrieve a push rule. + * \param scope + * ``global`` to specify global rules. + * \param kind + * The kind of rule + * \param ruleId + * The identifier for the rule. + */ explicit GetPushRuleJob(const QString& scope, const QString& kind, const QString& ruleId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetPushRuleJob. This function can be used when - * a URL for GetPushRuleJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetPushRuleJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& scope, const QString& kind, const QString& ruleId); @@ -58,6 +78,7 @@ namespace QMatrixClient // Result properties + /// The push rule. const PushRule& data() const; protected: @@ -68,34 +89,88 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Delete a push rule. + /// + /// This endpoint removes the push rule defined in the path. class DeletePushRuleJob : public BaseJob { public: + /*! Delete a push rule. + * \param scope + * ``global`` to specify global rules. + * \param kind + * The kind of rule + * \param ruleId + * The identifier for the rule. + */ explicit DeletePushRuleJob(const QString& scope, const QString& kind, const QString& ruleId); - /** Construct a URL out of baseUrl and usual parameters passed to - * DeletePushRuleJob. This function can be used when - * a URL for DeletePushRuleJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * DeletePushRuleJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& scope, const QString& kind, const QString& ruleId); }; + /// Add or change a push rule. + /// + /// This endpoint allows the creation, modification and deletion of pushers + /// for this user ID. The behaviour of this endpoint varies depending on the + /// values in the JSON body. class SetPushRuleJob : public BaseJob { public: + /*! Add or change a push rule. + * \param scope + * ``global`` to specify global rules. + * \param kind + * The kind of rule + * \param ruleId + * The identifier for the rule. + * \param actions + * The action(s) to perform when the conditions for this rule are met. + * \param before + * Use 'before' with a ``rule_id`` as its value to make the new rule the + * next-most important rule with respect to the given user defined rule. + * It is not possible to add a rule relative to a predefined server rule. + * \param after + * This makes the new rule the next-less important rule relative to the + * given user defined rule. It is not possible to add a rule relative + * to a predefined server rule. + * \param conditions + * The conditions that must hold true for an event in order for a + * rule to be applied to an event. A rule with no conditions + * always matches. Only applicable to ``underride`` and ``override`` rules. + * \param pattern + * Only applicable to ``content`` rules. The glob-style pattern to match against. + */ explicit SetPushRuleJob(const QString& scope, const QString& kind, const QString& ruleId, const QStringList& actions, const QString& before = {}, const QString& after = {}, const QVector<PushCondition>& conditions = {}, const QString& pattern = {}); }; + /// Get whether a push rule is enabled + /// + /// This endpoint gets whether the specified push rule is enabled. class IsPushRuleEnabledJob : public BaseJob { public: + /*! Get whether a push rule is enabled + * \param scope + * Either ``global`` or ``device/<profile_tag>`` to specify global + * rules or device rules for the given ``profile_tag``. + * \param kind + * The kind of rule + * \param ruleId + * The identifier for the rule. + */ explicit IsPushRuleEnabledJob(const QString& scope, const QString& kind, const QString& ruleId); - /** Construct a URL out of baseUrl and usual parameters passed to - * IsPushRuleEnabledJob. This function can be used when - * a URL for IsPushRuleEnabledJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * IsPushRuleEnabledJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& scope, const QString& kind, const QString& ruleId); @@ -104,6 +179,7 @@ namespace QMatrixClient // Result properties + /// Whether the push rule is enabled or not. bool enabled() const; protected: @@ -114,20 +190,46 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Enable or disable a push rule. + /// + /// This endpoint allows clients to enable or disable the specified push rule. class SetPushRuleEnabledJob : public BaseJob { public: + /*! Enable or disable a push rule. + * \param scope + * ``global`` to specify global rules. + * \param kind + * The kind of rule + * \param ruleId + * The identifier for the rule. + * \param enabled + * Whether the push rule is enabled or not. + */ explicit SetPushRuleEnabledJob(const QString& scope, const QString& kind, const QString& ruleId, bool enabled); }; + /// The actions for a push rule + /// + /// This endpoint get the actions for the specified push rule. class GetPushRuleActionsJob : public BaseJob { public: + /*! The actions for a push rule + * \param scope + * Either ``global`` or ``device/<profile_tag>`` to specify global + * rules or device rules for the given ``profile_tag``. + * \param kind + * The kind of rule + * \param ruleId + * The identifier for the rule. + */ explicit GetPushRuleActionsJob(const QString& scope, const QString& kind, const QString& ruleId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetPushRuleActionsJob. This function can be used when - * a URL for GetPushRuleActionsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetPushRuleActionsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& scope, const QString& kind, const QString& ruleId); @@ -136,6 +238,7 @@ namespace QMatrixClient // Result properties + /// The action(s) to perform for this rule. const QStringList& actions() const; protected: @@ -146,9 +249,23 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Set the actions for a push rule. + /// + /// This endpoint allows clients to change the actions of a push rule. + /// This can be used to change the actions of builtin rules. class SetPushRuleActionsJob : public BaseJob { public: + /*! Set the actions for a push rule. + * \param scope + * ``global`` to specify global rules. + * \param kind + * The kind of rule + * \param ruleId + * The identifier for the rule. + * \param actions + * The action(s) to perform for this rule. + */ explicit SetPushRuleActionsJob(const QString& scope, const QString& kind, const QString& ruleId, const QStringList& actions); }; } // namespace QMatrixClient diff --git a/lib/csapi/receipts.h b/lib/csapi/receipts.h index 3c11bcb1..101f2d05 100644 --- a/lib/csapi/receipts.h +++ b/lib/csapi/receipts.h @@ -12,9 +12,24 @@ namespace QMatrixClient { // Operations + /// Send a receipt for the given event ID. + /// + /// This API updates the marker for the given receipt type to the event ID + /// specified. class PostReceiptJob : public BaseJob { public: + /*! Send a receipt for the given event ID. + * \param roomId + * The room in which to send the event. + * \param receiptType + * The type of receipt to send. + * \param eventId + * The event ID to acknowledge up to. + * \param receipt + * Extra receipt information to attach to ``content`` if any. The + * server will automatically set the ``ts`` field. + */ explicit PostReceiptJob(const QString& roomId, const QString& receiptType, const QString& eventId, const QJsonObject& receipt = {}); }; } // namespace QMatrixClient diff --git a/lib/csapi/redaction.h b/lib/csapi/redaction.h index e74c9ce4..1e01f41b 100644 --- a/lib/csapi/redaction.h +++ b/lib/csapi/redaction.h @@ -11,14 +11,36 @@ namespace QMatrixClient { // Operations + /// Strips all non-integrity-critical information out of an event. + /// + /// Strips all information out of an event which isn't critical to the + /// integrity of the server-side representation of the room. + /// + /// This cannot be undone. + /// + /// Users may redact their own events, and any user with a power level + /// greater than or equal to the `redact` power level of the room may + /// redact events there. class RedactEventJob : public BaseJob { public: + /*! Strips all non-integrity-critical information out of an event. + * \param roomId + * The room from which to redact the event. + * \param eventId + * The ID of the event to redact + * \param txnId + * The transaction ID for this event. Clients should generate a + * unique ID; it will be used by the server to ensure idempotency of requests. + * \param reason + * The reason for the event being redacted. + */ explicit RedactEventJob(const QString& roomId, const QString& eventId, const QString& txnId, const QString& reason = {}); ~RedactEventJob() override; // Result properties + /// A unique identifier for the event. const QString& eventId() const; protected: 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: diff --git a/lib/csapi/report_content.h b/lib/csapi/report_content.h index 9d59db00..aa5f8a6b 100644 --- a/lib/csapi/report_content.h +++ b/lib/csapi/report_content.h @@ -12,9 +12,24 @@ namespace QMatrixClient { // Operations + /// Reports an event as inappropriate. + /// + /// Reports an event as inappropriate to the server, which may then notify + /// the appropriate people. class ReportContentJob : public BaseJob { public: + /*! Reports an event as inappropriate. + * \param roomId + * The room in which the event being reported is located. + * \param eventId + * The event to report. + * \param score + * The score to rate this content as where -100 is most offensive + * and 0 is inoffensive. + * \param reason + * The reason the content is being reported. May be blank. + */ explicit ReportContentJob(const QString& roomId, const QString& eventId, int score, const QString& reason); }; } // namespace QMatrixClient diff --git a/lib/csapi/room_send.h b/lib/csapi/room_send.h index 27bea13d..915a8f78 100644 --- a/lib/csapi/room_send.h +++ b/lib/csapi/room_send.h @@ -12,14 +12,42 @@ namespace QMatrixClient { // Operations + /// Send a message event to the given room. + /// + /// This endpoint is used to send a message event to a room. Message events + /// allow access to historical events and pagination, making them suited + /// for "once-off" activity in a room. + /// + /// The body of the request should be the content object of the event; the + /// fields in this object will vary depending on the type of event. See + /// `Room Events`_ for the m. event specification. class SendMessageJob : public BaseJob { public: + /*! Send a message event to the given room. + * \param roomId + * The room to send the event to. + * \param eventType + * The type of event to send. + * \param txnId + * The transaction ID for this event. Clients should generate an + * ID unique across requests with the same access token; it will be + * used by the server to ensure idempotency of requests. + * \param body + * This endpoint is used to send a message event to a room. Message events + * allow access to historical events and pagination, making them suited + * for "once-off" activity in a room. + * + * The body of the request should be the content object of the event; the + * fields in this object will vary depending on the type of event. See + * `Room Events`_ for the m. event specification. + */ explicit SendMessageJob(const QString& roomId, const QString& eventType, const QString& txnId, const QJsonObject& body = {}); ~SendMessageJob() override; // Result properties + /// A unique identifier for the event. const QString& eventId() const; protected: diff --git a/lib/csapi/room_state.h b/lib/csapi/room_state.h index a9e859c2..77ddf3e6 100644 --- a/lib/csapi/room_state.h +++ b/lib/csapi/room_state.h @@ -12,14 +12,48 @@ namespace QMatrixClient { // Operations + /// Send a state event to the given room. + /// + /// State events can be sent using this endpoint. These events will be + /// overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all + /// match. + /// + /// Requests to this endpoint **cannot use transaction IDs** + /// like other ``PUT`` paths because they cannot be differentiated from the + /// ``state_key``. Furthermore, ``POST`` is unsupported on state paths. + /// + /// The body of the request should be the content object of the event; the + /// fields in this object will vary depending on the type of event. See + /// `Room Events`_ for the ``m.`` event specification. class SetRoomStateWithKeyJob : public BaseJob { public: + /*! Send a state event to the given room. + * \param roomId + * The room to set the state in + * \param eventType + * The type of event to send. + * \param stateKey + * The state_key for the state to send. Defaults to the empty string. + * \param body + * State events can be sent using this endpoint. These events will be + * overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all + * match. + * + * Requests to this endpoint **cannot use transaction IDs** + * like other ``PUT`` paths because they cannot be differentiated from the + * ``state_key``. Furthermore, ``POST`` is unsupported on state paths. + * + * The body of the request should be the content object of the event; the + * fields in this object will vary depending on the type of event. See + * `Room Events`_ for the ``m.`` event specification. + */ explicit SetRoomStateWithKeyJob(const QString& roomId, const QString& eventType, const QString& stateKey, const QJsonObject& body = {}); ~SetRoomStateWithKeyJob() override; // Result properties + /// A unique identifier for the event. const QString& eventId() const; protected: @@ -30,14 +64,48 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Send a state event to the given room. + /// + /// State events can be sent using this endpoint. This endpoint is + /// equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}` + /// with an empty `stateKey`. Previous state events with matching + /// `<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten. + /// + /// Requests to this endpoint **cannot use transaction IDs** + /// like other ``PUT`` paths because they cannot be differentiated from the + /// ``state_key``. Furthermore, ``POST`` is unsupported on state paths. + /// + /// The body of the request should be the content object of the event; the + /// fields in this object will vary depending on the type of event. See + /// `Room Events`_ for the ``m.`` event specification. class SetRoomStateJob : public BaseJob { public: + /*! Send a state event to the given room. + * \param roomId + * The room to set the state in + * \param eventType + * The type of event to send. + * \param body + * State events can be sent using this endpoint. This endpoint is + * equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}` + * with an empty `stateKey`. Previous state events with matching + * `<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten. + * + * Requests to this endpoint **cannot use transaction IDs** + * like other ``PUT`` paths because they cannot be differentiated from the + * ``state_key``. Furthermore, ``POST`` is unsupported on state paths. + * + * The body of the request should be the content object of the event; the + * fields in this object will vary depending on the type of event. See + * `Room Events`_ for the ``m.`` event specification. + */ explicit SetRoomStateJob(const QString& roomId, const QString& eventType, const QJsonObject& body = {}); ~SetRoomStateJob() override; // Result properties + /// A unique identifier for the event. const QString& eventId() const; protected: diff --git a/lib/csapi/rooms.h b/lib/csapi/rooms.h index 7d690ec8..5b09f43f 100644 --- a/lib/csapi/rooms.h +++ b/lib/csapi/rooms.h @@ -15,14 +15,25 @@ namespace QMatrixClient { // Operations + /// Get a single event by event ID. + /// + /// Get a single event based on ``roomId/eventId``. You must have permission to + /// retrieve this event e.g. by being a member in the room for this event. class GetOneRoomEventJob : public BaseJob { public: + /*! Get a single event by event ID. + * \param roomId + * The ID of the room the event is in. + * \param eventId + * The event ID to get. + */ explicit GetOneRoomEventJob(const QString& roomId, const QString& eventId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetOneRoomEventJob. This function can be used when - * a URL for GetOneRoomEventJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetOneRoomEventJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId, const QString& eventId); @@ -31,6 +42,7 @@ namespace QMatrixClient // Result properties + /// The full event. EventPtr&& data(); protected: @@ -41,14 +53,29 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Get the state identified by the type and key. + /// + /// Looks up the contents of a state event in a room. If the user is + /// joined to the room then the state is taken from the current + /// state of the room. If the user has left the room then the state is + /// taken from the state of the room when they left. class GetRoomStateWithKeyJob : public BaseJob { public: + /*! Get the state identified by the type and key. + * \param roomId + * The room to look up the state in. + * \param eventType + * The type of state to look up. + * \param stateKey + * The key of the state to look up. + */ explicit GetRoomStateWithKeyJob(const QString& roomId, const QString& eventType, const QString& stateKey); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetRoomStateWithKeyJob. This function can be used when - * a URL for GetRoomStateWithKeyJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetRoomStateWithKeyJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId, const QString& eventType, const QString& stateKey); @@ -57,6 +84,7 @@ namespace QMatrixClient // Result properties + /// The content of the state event. StateEventPtr&& data(); protected: @@ -67,14 +95,29 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Get the state identified by the type, with the empty state key. + /// + /// Looks up the contents of a state event in a room. If the user is + /// joined to the room then the state is taken from the current + /// state of the room. If the user has left the room then the state is + /// taken from the state of the room when they left. + /// + /// This looks up the state event with the empty state key. class GetRoomStateByTypeJob : public BaseJob { public: + /*! Get the state identified by the type, with the empty state key. + * \param roomId + * The room to look up the state in. + * \param eventType + * The type of state to look up. + */ explicit GetRoomStateByTypeJob(const QString& roomId, const QString& eventType); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetRoomStateByTypeJob. This function can be used when - * a URL for GetRoomStateByTypeJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetRoomStateByTypeJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId, const QString& eventType); @@ -83,6 +126,7 @@ namespace QMatrixClient // Result properties + /// The content of the state event. StateEventPtr&& data(); protected: @@ -93,14 +137,22 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Get all state events in the current state of a room. + /// + /// Get the state events for the current state of a room. class GetRoomStateJob : public BaseJob { public: + /*! Get all state events in the current state of a room. + * \param roomId + * The room to look up the state for. + */ explicit GetRoomStateJob(const QString& roomId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetRoomStateJob. This function can be used when - * a URL for GetRoomStateJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetRoomStateJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId); @@ -109,6 +161,10 @@ namespace QMatrixClient // Result properties + /// If the user is a member of the room this will be the + /// current state of the room as a list of events. If the user + /// has left the room then this will be the state of the room + /// when they left as a list of events. StateEvents&& data(); protected: @@ -119,14 +175,22 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Get the m.room.member events for the room. + /// + /// Get the list of members for this room. class GetMembersByRoomJob : public BaseJob { public: + /*! Get the m.room.member events for the room. + * \param roomId + * The room to get the member events for. + */ explicit GetMembersByRoomJob(const QString& roomId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetMembersByRoomJob. This function can be used when - * a URL for GetMembersByRoomJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetMembersByRoomJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId); @@ -135,6 +199,7 @@ namespace QMatrixClient // Result properties + /// Get the list of members for this room. EventsArray<RoomMemberEvent>&& chunk(); protected: @@ -145,24 +210,35 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Gets the list of currently joined users and their profile data. + /// + /// This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. This API is primarily for Application Services and should be faster to respond than ``/members`` as it can be implemented more efficiently on the server. class GetJoinedMembersByRoomJob : public BaseJob { public: // Inner data structures + /// This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. This API is primarily for Application Services and should be faster to respond than ``/members`` as it can be implemented more efficiently on the server. struct RoomMember { + /// The display name of the user this object is representing. QString displayName; + /// The mxc avatar url of the user this object is representing. QString avatarUrl; }; // Construction/destruction + /*! Gets the list of currently joined users and their profile data. + * \param roomId + * The room to get the members of. + */ explicit GetJoinedMembersByRoomJob(const QString& roomId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetJoinedMembersByRoomJob. This function can be used when - * a URL for GetJoinedMembersByRoomJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetJoinedMembersByRoomJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId); @@ -171,6 +247,7 @@ namespace QMatrixClient // Result properties + /// A map from user ID to a RoomMember object. const QHash<QString, RoomMember>& joined() const; protected: diff --git a/lib/csapi/search.h b/lib/csapi/search.h index 7508aa0e..e1995cff 100644 --- a/lib/csapi/search.h +++ b/lib/csapi/search.h @@ -17,95 +17,182 @@ namespace QMatrixClient { // Operations + /// Perform a server-side search. + /// + /// Performs a full text search across different categories. class SearchJob : public BaseJob { public: // Inner data structures + /// Configures whether any context for the events + /// returned are included in the response. struct IncludeEventContext { + /// How many events before the result are + /// returned. By default, this is ``5``. Omittable<int> beforeLimit; + /// How many events after the result are + /// returned. By default, this is ``5``. Omittable<int> afterLimit; + /// Requests that the server returns the + /// historic profile information for the users + /// that sent the events that were returned. + /// By default, this is ``false``. bool includeProfile; }; + /// Configuration for group. struct Group { + /// Key that defines the group. QString key; }; + /// Requests that the server partitions the result set + /// based on the provided list of keys. struct Groupings { + /// List of groups to request. QVector<Group> groupBy; }; + /// Mapping of category name to search criteria. struct RoomEventsCriteria { + /// The string to search events for QString searchTerm; + /// The keys to search. Defaults to all. QStringList keys; + /// This takes a `filter`_. QJsonObject filter; + /// The order in which to search for results. + /// By default, this is ``"rank"``. QString orderBy; + /// Configures whether any context for the events + /// returned are included in the response. Omittable<IncludeEventContext> eventContext; + /// Requests the server return the current state for + /// each room returned. bool includeState; + /// Requests that the server partitions the result set + /// based on the provided list of keys. Omittable<Groupings> groupings; }; + /// Describes which categories to search in and their criteria. struct Categories { + /// Mapping of category name to search criteria. Omittable<RoomEventsCriteria> roomEvents; }; + /// Performs a full text search across different categories. struct UserProfile { + /// Performs a full text search across different categories. QString displayname; + /// Performs a full text search across different categories. QString avatarUrl; }; + /// Context for result, if requested. struct EventContext { + /// Pagination token for the start of the chunk QString begin; + /// Pagination token for the end of the chunk QString end; + /// The historic profile information of the + /// users that sent the events returned. + /// + /// The ``string`` key is the user ID for which + /// the profile belongs to. QHash<QString, UserProfile> profileInfo; + /// Events just before the result. RoomEvents eventsBefore; + /// Events just after the result. RoomEvents eventsAfter; }; + /// The result object. struct Result { + /// A number that describes how closely this result matches the search. Higher is closer. Omittable<double> rank; + /// The event that matched. RoomEventPtr result; + /// Context for result, if requested. Omittable<EventContext> context; }; + /// The results for a particular group value. struct GroupValue { + /// Token that can be used to get the next batch + /// of results in the group, by passing as the + /// `next_batch` parameter to the next call. If + /// this field is absent, there are no more + /// results in this group. QString nextBatch; + /// Key that can be used to order different + /// groups. Omittable<int> order; + /// Which results are in this group. QStringList results; }; + /// Mapping of category name to search criteria. struct ResultRoomEvents { + /// An approximate count of the total number of results found. Omittable<qint64> count; + /// List of words which should be highlighted, useful for stemming which may change the query terms. QStringList highlights; + /// List of results in the requested order. std::vector<Result> results; + /// The current state for every room in the results. + /// This is included if the request had the + /// ``include_state`` key set with a value of ``true``. + /// + /// The ``string`` key is the room ID for which the ``State + /// Event`` array belongs to. std::unordered_map<QString, StateEvents> state; + /// Any groups that were requested. + /// + /// The outer ``string`` key is the group key requested (eg: ``room_id`` + /// or ``sender``). The inner ``string`` key is the grouped value (eg: + /// a room's ID or a user's ID). QHash<QString, QHash<QString, GroupValue>> groups; + /// Token that can be used to get the next batch of + /// results, by passing as the `next_batch` parameter to + /// the next call. If this field is absent, there are no + /// more results. QString nextBatch; }; + /// Describes which categories to search in and their criteria. struct ResultCategories { + /// Mapping of category name to search criteria. Omittable<ResultRoomEvents> roomEvents; }; // Construction/destruction + /*! Perform a server-side search. + * \param searchCategories + * Describes which categories to search in and their criteria. + * \param nextBatch + * The point to return events from. If given, this should be a + * `next_batch` result from a previous call to this endpoint. + */ explicit SearchJob(const Categories& searchCategories, const QString& nextBatch = {}); ~SearchJob() override; // Result properties + /// Describes which categories to search in and their criteria. const ResultCategories& searchCategories() const; protected: diff --git a/lib/csapi/tags.h b/lib/csapi/tags.h index 29359745..e8664390 100644 --- a/lib/csapi/tags.h +++ b/lib/csapi/tags.h @@ -12,14 +12,25 @@ namespace QMatrixClient { // Operations + /// List the tags for a room. + /// + /// List the tags set by a user on a room. class GetRoomTagsJob : public BaseJob { public: + /*! List the tags for a room. + * \param userId + * The id of the user to get tags for. The access token must be + * authorized to make requests for this user id. + * \param roomId + * The id of the room to get tags for. + */ explicit GetRoomTagsJob(const QString& userId, const QString& roomId); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetRoomTagsJob. This function can be used when - * a URL for GetRoomTagsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetRoomTagsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId, const QString& roomId); @@ -28,6 +39,7 @@ namespace QMatrixClient // Result properties + /// List the tags set by a user on a room. const QJsonObject& tags() const; protected: @@ -38,20 +50,47 @@ namespace QMatrixClient QScopedPointer<Private> d; }; + /// Add a tag to a room. + /// + /// Add a tag to the room. class SetRoomTagJob : public BaseJob { public: + /*! Add a tag to a room. + * \param userId + * The id of the user to add a tag for. The access token must be + * authorized to make requests for this user id. + * \param roomId + * The id of the room to add a tag to. + * \param tag + * The tag to add. + * \param body + * Extra data for the tag, e.g. ordering. + */ explicit SetRoomTagJob(const QString& userId, const QString& roomId, const QString& tag, const QJsonObject& body = {}); }; + /// Remove a tag from the room. + /// + /// Remove a tag from the room. class DeleteRoomTagJob : public BaseJob { public: + /*! Remove a tag from the room. + * \param userId + * The id of the user to remove a tag for. The access token must be + * authorized to make requests for this user id. + * \param roomId + * The id of the room to remove a tag from. + * \param tag + * The tag to remove. + */ explicit DeleteRoomTagJob(const QString& userId, const QString& roomId, const QString& tag); - /** Construct a URL out of baseUrl and usual parameters passed to - * DeleteRoomTagJob. This function can be used when - * a URL for DeleteRoomTagJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * DeleteRoomTagJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& userId, const QString& roomId, const QString& tag); diff --git a/lib/csapi/third_party_membership.h b/lib/csapi/third_party_membership.h index d0c9f811..e8276b3c 100644 --- a/lib/csapi/third_party_membership.h +++ b/lib/csapi/third_party_membership.h @@ -11,9 +11,65 @@ namespace QMatrixClient { // Operations + /// Invite a user to participate in a particular room. + /// + /// .. _invite-by-third-party-id-endpoint: + /// + /// *Note that there are two forms of this API, which are documented separately. + /// This version of the API does not require that the inviter know the Matrix + /// identifier of the invitee, and instead relies on third party identifiers. + /// The homeserver uses an identity server to perform the mapping from + /// third party identifier to a Matrix identifier. The other is documented in the* + /// `joining rooms section`_. + /// + /// This API invites a user to participate in a particular room. + /// They do not start participating in the room until they actually join the + /// room. + /// + /// Only users currently in a particular room can invite other users to + /// join that room. + /// + /// If the identity server did know the Matrix user identifier for the + /// third party identifier, the homeserver will append a ``m.room.member`` + /// event to the room. + /// + /// If the identity server does not know a Matrix user identifier for the + /// passed third party identifier, the homeserver will issue an invitation + /// which can be accepted upon providing proof of ownership of the third + /// party identifier. This is achieved by the identity server generating a + /// token, which it gives to the inviting homeserver. The homeserver will + /// add an ``m.room.third_party_invite`` event into the graph for the room, + /// containing that token. + /// + /// When the invitee binds the invited third party identifier to a Matrix + /// user ID, the identity server will give the user a list of pending + /// invitations, each containing: + /// + /// - The room ID to which they were invited + /// + /// - The token given to the homeserver + /// + /// - A signature of the token, signed with the identity server's private key + /// + /// - The matrix user ID who invited them to the room + /// + /// If a token is requested from the identity server, the homeserver will + /// append a ``m.room.third_party_invite`` event to the room. + /// + /// .. _joining rooms section: `invite-by-user-id-endpoint`_ class InviteBy3PIDJob : public BaseJob { public: + /*! Invite a user to participate in a particular room. + * \param roomId + * The room identifier (not alias) to which to invite the user. + * \param idServer + * The hostname+port of the identity server which should be used for third party identifier lookups. + * \param medium + * The kind of address being passed in the address field, for example ``email``. + * \param address + * The invitee's third party identifier. + */ explicit InviteBy3PIDJob(const QString& roomId, const QString& idServer, const QString& medium, const QString& address); }; } // namespace QMatrixClient diff --git a/lib/csapi/to_device.h b/lib/csapi/to_device.h index e3f3b9e8..6aff3ae5 100644 --- a/lib/csapi/to_device.h +++ b/lib/csapi/to_device.h @@ -13,9 +13,25 @@ namespace QMatrixClient { // Operations + /// Send an event to a given set of devices. + /// + /// This endpoint is used to send send-to-device events to a set of + /// client devices. class SendToDeviceJob : public BaseJob { public: + /*! Send an event to a given set of devices. + * \param eventType + * The type of event to send. + * \param txnId + * The transaction ID for this event. Clients should generate an + * ID unique across requests with the same access token; it will be + * used by the server to ensure idempotency of requests. + * \param messages + * The messages to send. A map from user ID, to a map from + * device ID to message body. The device ID may also be `*`, + * meaning all known devices for the user. + */ explicit SendToDeviceJob(const QString& eventType, const QString& txnId, const QHash<QString, QHash<QString, QJsonObject>>& messages = {}); }; } // namespace QMatrixClient diff --git a/lib/csapi/typing.h b/lib/csapi/typing.h index f4fa36e8..aec489c2 100644 --- a/lib/csapi/typing.h +++ b/lib/csapi/typing.h @@ -12,9 +12,26 @@ namespace QMatrixClient { // Operations + /// Informs the server that the user has started or stopped typing. + /// + /// This tells the server that the user is typing for the next N + /// milliseconds where N is the value specified in the ``timeout`` key. + /// Alternatively, if ``typing`` is ``false``, it tells the server that the + /// user has stopped typing. class SetTypingJob : public BaseJob { public: + /*! Informs the server that the user has started or stopped typing. + * \param userId + * The user who has started to type. + * \param roomId + * The room in which the user is typing. + * \param typing + * Whether the user is typing or not. If ``false``, the ``timeout`` + * key can be omitted. + * \param timeout + * The length of time in milliseconds to mark this user as typing. + */ explicit SetTypingJob(const QString& userId, const QString& roomId, bool typing, Omittable<int> timeout = none); }; } // namespace QMatrixClient diff --git a/lib/csapi/users.h b/lib/csapi/users.h index ecf1faaf..178d5c21 100644 --- a/lib/csapi/users.h +++ b/lib/csapi/users.h @@ -13,26 +13,43 @@ namespace QMatrixClient { // Operations + /// Searches the user directory. + /// + /// This API performs a server-side search over all users registered on the server. + /// It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms. class SearchUserDirectoryJob : public BaseJob { public: // Inner data structures + /// This API performs a server-side search over all users registered on the server. + /// It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms. struct User { + /// The user's matrix user ID. QString userId; + /// The display name of the user, if one exists. QString displayName; + /// The avatar url, as an MXC, if one exists. QString avatarUrl; }; // Construction/destruction + /*! Searches the user directory. + * \param searchTerm + * The term to search for + * \param limit + * The maximum number of results to return (Defaults to 10). + */ explicit SearchUserDirectoryJob(const QString& searchTerm, Omittable<int> limit = none); ~SearchUserDirectoryJob() override; // Result properties + /// Ordered by rank and then whether or not profile info is available. const QVector<User>& results() const; + /// Indicates if the result list has been truncated by the limit. bool limited() const; protected: diff --git a/lib/csapi/versions.h b/lib/csapi/versions.h index 9f1a4831..3303752d 100644 --- a/lib/csapi/versions.h +++ b/lib/csapi/versions.h @@ -11,14 +11,23 @@ namespace QMatrixClient { // Operations + /// Gets the versions of the specification supported by the server. + /// + /// Gets the versions of the specification supported by the server. + /// + /// Values will take the form ``rX.Y.Z``. + /// + /// Only the latest ``Z`` value will be reported for each supported ``X.Y`` value. + /// i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``. class GetVersionsJob : public BaseJob { public: explicit GetVersionsJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetVersionsJob. This function can be used when - * a URL for GetVersionsJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetVersionsJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -27,6 +36,7 @@ namespace QMatrixClient // Result properties + /// The supported versions. const QStringList& versions() const; protected: diff --git a/lib/csapi/voip.h b/lib/csapi/voip.h index fafbaf4a..ca190df7 100644 --- a/lib/csapi/voip.h +++ b/lib/csapi/voip.h @@ -12,14 +12,19 @@ namespace QMatrixClient { // Operations + /// Obtain TURN server credentials. + /// + /// This API provides credentials for the client to use when initiating + /// calls. class GetTurnServerJob : public BaseJob { public: explicit GetTurnServerJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetTurnServerJob. This function can be used when - * a URL for GetTurnServerJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetTurnServerJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -28,6 +33,7 @@ namespace QMatrixClient // Result properties + /// The TURN server credentials. const QJsonObject& data() const; protected: diff --git a/lib/csapi/whoami.h b/lib/csapi/whoami.h index b9be8e70..1ada7406 100644 --- a/lib/csapi/whoami.h +++ b/lib/csapi/whoami.h @@ -11,14 +11,25 @@ namespace QMatrixClient { // Operations + /// Gets information about the owner of an access token. + /// + /// Gets information about the owner of a given access token. + /// + /// Note that, as with the rest of the Client-Server API, + /// Application Services may masquerade as users within their + /// namespace by giving a ``user_id`` query parameter. In this + /// situation, the server should verify that the given ``user_id`` + /// is registered by the appservice, and return it in the response + /// body. class GetTokenOwnerJob : public BaseJob { public: explicit GetTokenOwnerJob(); - /** Construct a URL out of baseUrl and usual parameters passed to - * GetTokenOwnerJob. This function can be used when - * a URL for GetTokenOwnerJob is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * GetTokenOwnerJob is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); @@ -27,6 +38,7 @@ namespace QMatrixClient // Result properties + /// The user id that owns the access token. const QString& userId() const; protected: diff --git a/lib/csapi/{{base}}.h.mustache b/lib/csapi/{{base}}.h.mustache index bd04ff08..38d80669 100644 --- a/lib/csapi/{{base}}.h.mustache +++ b/lib/csapi/{{base}}.h.mustache @@ -10,10 +10,12 @@ namespace QMatrixClient { {{#models}} // Data structures -{{# model}} +{{# model}}{{#description}} + /// {{_}}{{/description}} struct {{name}}{{#parents?}} : {{#parents}}{{name}}{{>cjoin}}{{/parents}}{{/parents?}} { -{{#vars}} {{>maybeOmittableType}} {{nameCamelCase}}; +{{#vars}}{{#description}} /// {{_}} +{{/description}} {{>maybeOmittableType}} {{nameCamelCase}}; {{/vars}} }; {{#in?}} QJsonObject toJson(const {{name}}& pod); @@ -24,24 +26,34 @@ namespace QMatrixClient }; {{/ out?}}{{/model}} {{/models}}{{#operations}} // Operations -{{# operation}} +{{# operation}}{{#summary}} + /// {{summary}}{{#description?}}{{!add a linebreak between summary and description if both exist}} + /// {{/description?}}{{/summary}}{{#description}} + /// {{_}}{{/description}} class {{camelCaseOperationId}}Job : public BaseJob { public:{{#models}} // Inner data structures -{{# model}} +{{# model}}{{#description}} + /// {{_}}{{/description}} struct {{name}}{{#parents?}} : {{#parents}}{{name}}{{>cjoin}}{{/parents}}{{/parents?}} { -{{#vars}} {{>maybeOmittableType}} {{nameCamelCase}}; +{{#vars}}{{#description}} /// {{_}} +{{/description}} {{>maybeOmittableType}} {{nameCamelCase}}; {{/vars}} }; {{/ model}} // Construction/destruction -{{/ models}} +{{/ models}}{{#allParams?}} + /*! {{summary}}{{#allParams}} + * \param {{nameCamelCase}} {{#description}} + * {{_}}{{/description}}{{/allParams}} + */{{/allParams?}} explicit {{camelCaseOperationId}}Job({{#allParams}}{{>joinedParamDecl}}{{/allParams}});{{^bodyParams}} - /** Construct a URL out of baseUrl and usual parameters passed to - * {{camelCaseOperationId}}Job. This function can be used when - * a URL for {{camelCaseOperationId}}Job is necessary but the job + /*! Construct a URL without creating a full-fledged job object + * + * This function can be used when a URL for + * {{camelCaseOperationId}}Job is necessary but the job * itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl{{#allParams?}}, {{#allParams}}{{>joinedParamDecl}}{{/allParams}}{{/allParams?}}); @@ -49,7 +61,8 @@ namespace QMatrixClient ~{{camelCaseOperationId}}Job() override; // Result properties -{{#allProperties}} +{{#allProperties}}{{#description}} + /// {{_}}{{/description}} {{>maybeCrefType}} {{paramName}}(){{^moveOnly}} const{{/moveOnly}};{{/allProperties}} protected: |