diff options
Diffstat (limited to 'lib/csapi')
46 files changed, 89 insertions, 241 deletions
diff --git a/lib/csapi/account-data.h b/lib/csapi/account-data.h index 1c7b555b..9a31596f 100644 --- a/lib/csapi/account-data.h +++ b/lib/csapi/account-data.h @@ -18,7 +18,6 @@ class SetAccountDataJob : public BaseJob { public: /*! \brief 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. @@ -43,7 +42,6 @@ class GetAccountDataJob : public BaseJob { public: /*! \brief Get some account_data for the user. * - * * \param userId * The ID of the user to get account_data for. The access token must be * authorized to make requests for this user ID. @@ -73,7 +71,6 @@ class SetAccountDataPerRoomJob : public BaseJob { public: /*! \brief 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. @@ -102,7 +99,6 @@ class GetAccountDataPerRoomJob : public BaseJob { public: /*! \brief Get 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. diff --git a/lib/csapi/admin.h b/lib/csapi/admin.h index 6ad7d08d..570bf24a 100644 --- a/lib/csapi/admin.h +++ b/lib/csapi/admin.h @@ -59,7 +59,6 @@ public: /*! \brief Gets information about a particular user. * - * * \param userId * The user to look up. */ diff --git a/lib/csapi/administrative_contact.h b/lib/csapi/administrative_contact.h index 53c89272..1966d533 100644 --- a/lib/csapi/administrative_contact.h +++ b/lib/csapi/administrative_contact.h @@ -4,9 +4,9 @@ #pragma once -#include "csapi/./definitions/request_email_validation.h" -#include "csapi/./definitions/request_msisdn_validation.h" #include "csapi/definitions/auth_data.h" +#include "csapi/definitions/request_email_validation.h" +#include "csapi/definitions/request_msisdn_validation.h" #include "csapi/definitions/request_token_response.h" #include "jobs/basejob.h" @@ -124,7 +124,6 @@ public: /*! \brief Adds contact information to the user's account. * - * * \param threePidCreds * The third party credentials to associate with the account. */ @@ -158,7 +157,6 @@ class Add3PIDJob : public BaseJob { public: /*! \brief Adds contact information to the user's account. * - * * \param clientSecret * The client secret used in the session with the homeserver. * @@ -187,7 +185,6 @@ class Bind3PIDJob : public BaseJob { public: /*! \brief Binds a 3PID to the user's account through an Identity Service. * - * * \param clientSecret * The client secret used in the session with the identity server. * @@ -217,7 +214,6 @@ class Delete3pidFromAccountJob : public BaseJob { public: /*! \brief Deletes a third party identifier from the user's account * - * * \param medium * The medium of the third party identifier being removed. * @@ -261,7 +257,6 @@ class Unbind3pidFromAccountJob : public BaseJob { public: /*! \brief Removes a user's third party identifier from an identity server. * - * * \param medium * The medium of the third party identifier being removed. * @@ -307,7 +302,6 @@ public: /*! \brief Begins the validation process for an email address for * association with the user's account. * - * * \param body * The homeserver must check that the given email address is **not** * already associated with an account on this homeserver. This API should @@ -324,7 +318,7 @@ public: /// An email was sent to the given address. Note that this may be an /// email containing the validation token or it may be informing the /// user of an error. - RequestTokenResponse data() const + RequestTokenResponse response() const { return fromJson<RequestTokenResponse>(jsonData()); } @@ -346,7 +340,6 @@ public: /*! \brief Begins the validation process for a phone number for association * with the user's account. * - * * \param body * The homeserver must check that the given phone number is **not** * already associated with an account on this homeserver. This API should @@ -361,7 +354,7 @@ public: // Result properties /// An SMS message was sent to the given phone number. - RequestTokenResponse data() const + RequestTokenResponse response() const { return fromJson<RequestTokenResponse>(jsonData()); } diff --git a/lib/csapi/appservice_room_directory.h b/lib/csapi/appservice_room_directory.h index d103177c..3fa02a07 100644 --- a/lib/csapi/appservice_room_directory.h +++ b/lib/csapi/appservice_room_directory.h @@ -26,7 +26,6 @@ public: /*! \brief Updates a room's visibility in the application service's room * directory. * - * * \param networkId * The protocol (network) ID to update the room list for. This would * have been provided by the application service as being listed as diff --git a/lib/csapi/banning.h b/lib/csapi/banning.h index 4faaaa81..37ae91ee 100644 --- a/lib/csapi/banning.h +++ b/lib/csapi/banning.h @@ -22,7 +22,6 @@ class BanJob : public BaseJob { public: /*! \brief Ban a user in the room. * - * * \param roomId * The room identifier (not alias) from which the user should be banned. * @@ -50,7 +49,6 @@ class UnbanJob : public BaseJob { public: /*! \brief Unban a user from the room. * - * * \param roomId * The room identifier (not alias) from which the user should be unbanned. * diff --git a/lib/csapi/content-repo.h b/lib/csapi/content-repo.h index 0eb273bc..ed67485c 100644 --- a/lib/csapi/content-repo.h +++ b/lib/csapi/content-repo.h @@ -18,7 +18,6 @@ class UploadContentJob : public BaseJob { public: /*! \brief Upload some content to the content repository. * - * * \param content * The content to be uploaded. * @@ -47,7 +46,6 @@ class GetContentJob : public BaseJob { public: /*! \brief Download content from the content repository. * - * * \param serverName * The server name from the ``mxc://`` URI (the authoritory component) * @@ -85,15 +83,16 @@ public: QIODevice* data() { return reply(); } }; -/*! \brief Download content from the content repository. This is the same as -the download endpoint above, except permitting a desired file name. +/*! \brief Download content from the content repository overriding the file name * + * This will download content from the content repository (same as + * the previous endpoint) but replace the target file name with the one + * provided by the caller. */ class GetContentOverrideNameJob : public BaseJob { public: - /*! \brief Download content from the content repository. This is the same as -the download endpoint above, except permitting a desired file name. - * + /*! \brief Download content from the content repository overriding the file + * name * * \param serverName * The server name from the ``mxc://`` URI (the authoritory component) @@ -106,10 +105,8 @@ the download endpoint above, except permitting a desired file name. * * \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. + * 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, @@ -141,15 +138,14 @@ itself. Defaults to QIODevice* data() { return reply(); } }; -/*! \brief Download a thumbnail of content from the content repository. See the -`thumbnailing <#thumbnails>`_ section for more information. +/*! \brief Download a thumbnail of content from the content repository * + * Download a thumbnail of content from the content repository. + * See the `thumbnailing <#thumbnails>`_ section for more information. */ class GetContentThumbnailJob : public BaseJob { public: - /*! \brief Download a thumbnail of content from the content repository. See -the `thumbnailing <#thumbnails>`_ section for more information. - * + /*! \brief Download a thumbnail of content from the content repository * * \param serverName * The server name from the ``mxc://`` URI (the authoritory component) @@ -170,11 +166,9 @@ the `thumbnailing <#thumbnails>`_ section for more information. * section for more information. * * \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. + * 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, @@ -215,7 +209,6 @@ class GetUrlPreviewJob : public BaseJob { public: /*! \brief Get information about a URL for a client * - * * \param url * The URL to get a preview of. * diff --git a/lib/csapi/create_room.h b/lib/csapi/create_room.h index 82db9e59..6a718ff4 100644 --- a/lib/csapi/create_room.h +++ b/lib/csapi/create_room.h @@ -190,7 +190,6 @@ public: /*! \brief 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 diff --git a/lib/csapi/definitions/request_email_validation.h b/lib/csapi/definitions/request_email_validation.h index e6ab261d..ab34862e 100644 --- a/lib/csapi/definitions/request_email_validation.h +++ b/lib/csapi/definitions/request_email_validation.h @@ -6,7 +6,7 @@ #include "converters.h" -#include "csapi/./definitions/../../identity/definitions/request_email_validation.h" +#include "csapi/definitions/../../identity/definitions/request_email_validation.h" namespace Quotient { diff --git a/lib/csapi/definitions/request_msisdn_validation.h b/lib/csapi/definitions/request_msisdn_validation.h index 6f161f00..8539cd98 100644 --- a/lib/csapi/definitions/request_msisdn_validation.h +++ b/lib/csapi/definitions/request_msisdn_validation.h @@ -6,7 +6,7 @@ #include "converters.h" -#include "csapi/./definitions/../../identity/definitions/request_msisdn_validation.h" +#include "csapi/definitions/../../identity/definitions/request_msisdn_validation.h" namespace Quotient { diff --git a/lib/csapi/device_management.h b/lib/csapi/device_management.h index 0abd5b84..47dc7ec8 100644 --- a/lib/csapi/device_management.h +++ b/lib/csapi/device_management.h @@ -44,7 +44,6 @@ class GetDeviceJob : public BaseJob { public: /*! \brief Get a single device * - * * \param deviceId * The device to retrieve. */ @@ -60,7 +59,7 @@ public: // Result properties /// Device information - Device data() const { return fromJson<Device>(jsonData()); } + Device device() const { return fromJson<Device>(jsonData()); } }; /*! \brief Update a device @@ -71,7 +70,6 @@ class UpdateDeviceJob : public BaseJob { public: /*! \brief Update a device * - * * \param deviceId * The device to update. * @@ -93,7 +91,6 @@ class DeleteDeviceJob : public BaseJob { public: /*! \brief Delete a device * - * * \param deviceId * The device to delete. * @@ -116,7 +113,6 @@ class DeleteDevicesJob : public BaseJob { public: /*! \brief Bulk deletion of devices * - * * \param devices * The list of device IDs to delete. * diff --git a/lib/csapi/directory.h b/lib/csapi/directory.h index 7ae44d1d..9b109aad 100644 --- a/lib/csapi/directory.h +++ b/lib/csapi/directory.h @@ -15,7 +15,6 @@ class SetRoomAliasJob : public BaseJob { public: /*! \brief Create a new mapping from room alias to room ID. * - * * \param roomAlias * The room alias to set. * @@ -37,7 +36,6 @@ class GetRoomIdByAliasJob : public BaseJob { public: /*! \brief Get the room ID corresponding to this room alias. * - * * \param roomAlias * The room alias. */ @@ -82,7 +80,6 @@ class DeleteRoomAliasJob : public BaseJob { public: /*! \brief Remove a mapping of room alias to room ID. * - * * \param roomAlias * The room alias to remove. */ @@ -119,7 +116,6 @@ class GetLocalAliasesJob : public BaseJob { public: /*! \brief Get a list of local aliases on a given room. * - * * \param roomId * The room ID to find local aliases of. */ diff --git a/lib/csapi/event_context.h b/lib/csapi/event_context.h index 2f9c66d8..d82d16ab 100644 --- a/lib/csapi/event_context.h +++ b/lib/csapi/event_context.h @@ -23,7 +23,6 @@ class GetEventContextJob : public BaseJob { public: /*! \brief Get events and state around the specified event. * - * * \param roomId * The room to get events from. * diff --git a/lib/csapi/filter.h b/lib/csapi/filter.h index 9aa7dc79..f07b489c 100644 --- a/lib/csapi/filter.h +++ b/lib/csapi/filter.h @@ -20,7 +20,6 @@ class DefineFilterJob : public BaseJob { public: /*! \brief 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. @@ -46,7 +45,6 @@ class GetFilterJob : public BaseJob { public: /*! \brief Download a filter * - * * \param userId * The user ID to download a filter for. * @@ -65,8 +63,8 @@ public: // Result properties - /// "The filter defintion" - Filter data() const { return fromJson<Filter>(jsonData()); } + /// The filter definition. + Filter filter() const { return fromJson<Filter>(jsonData()); } }; } // namespace Quotient diff --git a/lib/csapi/inviting.h b/lib/csapi/inviting.h index a7ec6093..59a61b89 100644 --- a/lib/csapi/inviting.h +++ b/lib/csapi/inviting.h @@ -33,7 +33,6 @@ class InviteUserJob : public BaseJob { public: /*! \brief Invite a user to participate in a particular room. * - * * \param roomId * The room identifier (not alias) to which to invite the user. * diff --git a/lib/csapi/joining.h b/lib/csapi/joining.h index 6822fbdf..dd936f92 100644 --- a/lib/csapi/joining.h +++ b/lib/csapi/joining.h @@ -12,8 +12,8 @@ namespace Quotient { /*! \brief 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.* + * *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 @@ -22,34 +22,18 @@ namespace Quotient { * * 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: /*! \brief Start the requesting user participating in a particular room. * - * * \param roomId * The room identifier (not alias) to join. * * \param thirdPartySigned - * *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. + * If 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. */ explicit JoinRoomByIdJob( const QString& roomId, @@ -73,16 +57,11 @@ public: * * 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: /*! \brief Start the requesting user participating in a particular room. * - * * \param roomIdOrAlias * The room identifier or alias to join. * @@ -91,17 +70,6 @@ public: * must be participating in the room. * * \param thirdPartySigned - * *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. diff --git a/lib/csapi/keys.h b/lib/csapi/keys.h index b7a8dc71..8f6c8cc9 100644 --- a/lib/csapi/keys.h +++ b/lib/csapi/keys.h @@ -18,7 +18,6 @@ class UploadKeysJob : public BaseJob { public: /*! \brief Upload end-to-end encryption keys. * - * * \param deviceKeys * Identity keys for the device. May be absent if no new * identity keys are required. @@ -61,9 +60,7 @@ public: }; /// Returns the current devices and identity keys for the given users. - struct DeviceKeys : - - Quotient::DeviceKeys { + struct DeviceInformation : DeviceKeys { /// Additional data added to the device key information /// by intermediate servers, and not covered by the /// signatures. @@ -74,7 +71,6 @@ public: /*! \brief 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 @@ -113,9 +109,9 @@ public: /// the information returned will be the same as uploaded via /// ``/keys/upload``, with the addition of an ``unsigned`` /// property. - QHash<QString, QHash<QString, DeviceKeys>> deviceKeys() const + QHash<QString, QHash<QString, DeviceInformation>> deviceKeys() const { - return loadFromJson<QHash<QString, QHash<QString, DeviceKeys>>>( + return loadFromJson<QHash<QString, QHash<QString, DeviceInformation>>>( "device_keys"_ls); } }; @@ -130,8 +126,9 @@ struct JsonObjectConverter<QueryKeysJob::UnsignedDeviceInfo> { }; template <> -struct JsonObjectConverter<QueryKeysJob::DeviceKeys> { - static void fillFrom(const QJsonObject& jo, QueryKeysJob::DeviceKeys& result) +struct JsonObjectConverter<QueryKeysJob::DeviceInformation> { + static void fillFrom(const QJsonObject& jo, + QueryKeysJob::DeviceInformation& result) { fillFromJson<DeviceKeys>(jo, result); fromJson(jo.value("unsigned"_ls), result.unsignedData); @@ -146,7 +143,6 @@ class ClaimKeysJob : public BaseJob { public: /*! \brief 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. @@ -202,7 +198,6 @@ class GetKeysChangesJob : public BaseJob { public: /*! \brief 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 diff --git a/lib/csapi/kicking.h b/lib/csapi/kicking.h index 594f5845..2645a54f 100644 --- a/lib/csapi/kicking.h +++ b/lib/csapi/kicking.h @@ -24,7 +24,6 @@ class KickJob : public BaseJob { public: /*! \brief Kick a user from the room. * - * * \param roomId * The room identifier (not alias) from which the user should be kicked. * diff --git a/lib/csapi/leaving.h b/lib/csapi/leaving.h index 0a4c401c..1bea7e41 100644 --- a/lib/csapi/leaving.h +++ b/lib/csapi/leaving.h @@ -26,7 +26,6 @@ class LeaveRoomJob : public BaseJob { public: /*! \brief Stop the requesting user participating in a particular room. * - * * \param roomId * The room identifier to leave. */ @@ -56,7 +55,6 @@ class ForgetRoomJob : public BaseJob { public: /*! \brief Stop the requesting user remembering about a particular room. * - * * \param roomId * The room identifier to forget. */ diff --git a/lib/csapi/list_public_rooms.cpp b/lib/csapi/list_public_rooms.cpp index cdc5c716..415d816c 100644 --- a/lib/csapi/list_public_rooms.cpp +++ b/lib/csapi/list_public_rooms.cpp @@ -60,7 +60,9 @@ GetPublicRoomsJob::GetPublicRoomsJob(Omittable<int> limit, const QString& since, : BaseJob(HttpVerb::Get, QStringLiteral("GetPublicRoomsJob"), QStringLiteral("/_matrix/client/r0") % "/publicRooms", queryToGetPublicRooms(limit, since, server), {}, false) -{} +{ + addExpectedKey("chunk"); +} auto queryToQueryPublicRooms(const QString& server) { diff --git a/lib/csapi/list_public_rooms.h b/lib/csapi/list_public_rooms.h index 5ef7c23e..b0cb79d2 100644 --- a/lib/csapi/list_public_rooms.h +++ b/lib/csapi/list_public_rooms.h @@ -18,7 +18,6 @@ class GetRoomVisibilityOnDirectoryJob : public BaseJob { public: /*! \brief Gets the visibility of a room in the directory * - * * \param roomId * The room ID. */ @@ -53,7 +52,6 @@ class SetRoomVisibilityOnDirectoryJob : public BaseJob { public: /*! \brief Sets the visibility of a room in the room directory * - * * \param roomId * The room ID. * @@ -76,7 +74,6 @@ class GetPublicRoomsJob : public BaseJob { public: /*! \brief Lists the public rooms on the server. * - * * \param limit * Limit the number of results returned. * @@ -105,10 +102,27 @@ public: // Result properties - /// A list of the rooms on the server. - PublicRoomsResponse data() const + /// A paginated chunk of public rooms. + QVector<PublicRoomsChunk> chunk() const { - return fromJson<PublicRoomsResponse>(jsonData()); + return loadFromJson<QVector<PublicRoomsChunk>>("chunk"_ls); + } + + /// 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. + QString nextBatch() const { return loadFromJson<QString>("next_batch"_ls); } + + /// 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. + QString prevBatch() const { return loadFromJson<QString>("prev_batch"_ls); } + + /// An estimate on the total number of public rooms, if the + /// server has an estimate. + Omittable<int> totalRoomCountEstimate() const + { + return loadFromJson<Omittable<int>>("total_room_count_estimate"_ls); } }; @@ -130,38 +144,10 @@ public: 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. - int 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 /*! \brief 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. @@ -228,21 +214,4 @@ struct JsonObjectConverter<QueryPublicRoomsJob::Filter> { } }; -template <> -struct JsonObjectConverter<QueryPublicRoomsJob::PublicRoomsChunk> { - static void fillFrom(const QJsonObject& jo, - QueryPublicRoomsJob::PublicRoomsChunk& result) - { - fromJson(jo.value("aliases"_ls), result.aliases); - fromJson(jo.value("canonical_alias"_ls), result.canonicalAlias); - fromJson(jo.value("name"_ls), result.name); - fromJson(jo.value("num_joined_members"_ls), result.numJoinedMembers); - fromJson(jo.value("room_id"_ls), result.roomId); - fromJson(jo.value("topic"_ls), result.topic); - fromJson(jo.value("world_readable"_ls), result.worldReadable); - fromJson(jo.value("guest_can_join"_ls), result.guestCanJoin); - fromJson(jo.value("avatar_url"_ls), result.avatarUrl); - } -}; - } // namespace Quotient diff --git a/lib/csapi/login.h b/lib/csapi/login.h index 0483b77c..a406fc79 100644 --- a/lib/csapi/login.h +++ b/lib/csapi/login.h @@ -76,12 +76,20 @@ class LoginJob : public BaseJob { public: /*! \brief Authenticates the user. * - * * \param type * The login type being used. * * \param identifier - * Identification information for 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`_. * * \param password * Required when ``type`` is ``m.login.password``. The user's @@ -108,7 +116,7 @@ public: // Result properties - /// The fully-qualified Matrix ID that has been registered. + /// The fully-qualified Matrix ID for the account. QString userId() const { return loadFromJson<QString>("user_id"_ls); } /// An access token for the account. diff --git a/lib/csapi/message_pagination.h b/lib/csapi/message_pagination.h index e9f9e6d4..286d4237 100644 --- a/lib/csapi/message_pagination.h +++ b/lib/csapi/message_pagination.h @@ -22,7 +22,6 @@ class GetRoomEventsJob : public BaseJob { public: /*! \brief Get a list of events for this room * - * * \param roomId * The room to get events from. * diff --git a/lib/csapi/notifications.h b/lib/csapi/notifications.h index 095e9325..ff499c7a 100644 --- a/lib/csapi/notifications.h +++ b/lib/csapi/notifications.h @@ -42,7 +42,6 @@ public: /*! \brief Gets a list of events that the user has been notified about * - * * \param from * Pagination token given to retrieve the next set of events. * diff --git a/lib/csapi/openid.h b/lib/csapi/openid.h index e69f9ad0..efb5f623 100644 --- a/lib/csapi/openid.h +++ b/lib/csapi/openid.h @@ -25,7 +25,6 @@ class RequestOpenIdTokenJob : public BaseJob { public: /*! \brief Get an OpenID token object to verify the requester's identity. * - * * \param userId * The user to request and OpenID token for. Should be the user who * is authenticated for the request. @@ -39,11 +38,11 @@ public: // Result properties /// OpenID token information. This response is nearly compatible with the - /// response documented in the `OpenID 1.0 Specification + /// response documented in the `OpenID Connect 1.0 Specification /// <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_ /// with the only difference being the lack of an ``id_token``. Instead, /// the Matrix homeserver's name is provided. - OpenidToken data() const { return fromJson<OpenidToken>(jsonData()); } + OpenidToken tokenData() const { return fromJson<OpenidToken>(jsonData()); } }; } // namespace Quotient diff --git a/lib/csapi/peeking_events.h b/lib/csapi/peeking_events.h index bfb9e24a..cecd9f2d 100644 --- a/lib/csapi/peeking_events.h +++ b/lib/csapi/peeking_events.h @@ -26,7 +26,6 @@ class PeekEventsJob : public BaseJob { public: /*! \brief 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. diff --git a/lib/csapi/presence.h b/lib/csapi/presence.h index b34028e7..a885bf4f 100644 --- a/lib/csapi/presence.h +++ b/lib/csapi/presence.h @@ -19,7 +19,6 @@ class SetPresenceJob : public BaseJob { public: /*! \brief Update this user's presence state. * - * * \param userId * The user whose presence state to update. * @@ -41,7 +40,6 @@ class GetPresenceJob : public BaseJob { public: /*! \brief Get this user's presence state. * - * * \param userId * The user whose presence state to get. */ diff --git a/lib/csapi/profile.h b/lib/csapi/profile.h index 5b0d06d9..88bf3166 100644 --- a/lib/csapi/profile.h +++ b/lib/csapi/profile.h @@ -17,7 +17,6 @@ class SetDisplayNameJob : public BaseJob { public: /*! \brief Set the user's display name. * - * * \param userId * The user whose display name to set. * @@ -38,7 +37,6 @@ class GetDisplayNameJob : public BaseJob { public: /*! \brief Get the user's display name. * - * * \param userId * The user whose display name to get. */ @@ -69,7 +67,6 @@ class SetAvatarUrlJob : public BaseJob { public: /*! \brief Set the user's avatar URL. * - * * \param userId * The user whose avatar URL to set. * @@ -90,7 +87,6 @@ class GetAvatarUrlJob : public BaseJob { public: /*! \brief Get the user's avatar URL. * - * * \param userId * The user whose avatar URL to get. */ @@ -120,7 +116,6 @@ class GetUserProfileJob : public BaseJob { public: /*! \brief Get this user's profile information. * - * * \param userId * The user whose profile information to get. */ diff --git a/lib/csapi/pusher.h b/lib/csapi/pusher.h index 40cd5796..ae0050d2 100644 --- a/lib/csapi/pusher.h +++ b/lib/csapi/pusher.h @@ -132,7 +132,6 @@ public: /*! \brief 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 diff --git a/lib/csapi/pushrules.h b/lib/csapi/pushrules.h index 0971dc6b..f6d3458a 100644 --- a/lib/csapi/pushrules.h +++ b/lib/csapi/pushrules.h @@ -48,7 +48,6 @@ class GetPushRuleJob : public BaseJob { public: /*! \brief Retrieve a push rule. * - * * \param scope * ``global`` to specify global rules. * @@ -73,7 +72,7 @@ public: /// The specific push rule. This will also include keys specific to the /// rule itself such as the rule's ``actions`` and ``conditions`` if set. - PushRule data() const { return fromJson<PushRule>(jsonData()); } + PushRule pushRule() const { return fromJson<PushRule>(jsonData()); } }; /*! \brief Delete a push rule. @@ -84,7 +83,6 @@ class DeletePushRuleJob : public BaseJob { public: /*! \brief Delete a push rule. * - * * \param scope * ``global`` to specify global rules. * @@ -118,7 +116,6 @@ class SetPushRuleJob : public BaseJob { public: /*! \brief Add or change a push rule. * - * * \param scope * ``global`` to specify global rules. * @@ -166,7 +163,6 @@ class IsPushRuleEnabledJob : public BaseJob { public: /*! \brief 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``. @@ -202,7 +198,6 @@ class SetPushRuleEnabledJob : public BaseJob { public: /*! \brief Enable or disable a push rule. * - * * \param scope * ``global`` to specify global rules. * @@ -227,7 +222,6 @@ class GetPushRuleActionsJob : public BaseJob { public: /*! \brief 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``. @@ -267,7 +261,6 @@ class SetPushRuleActionsJob : public BaseJob { public: /*! \brief Set the actions for a push rule. * - * * \param scope * ``global`` to specify global rules. * diff --git a/lib/csapi/read_markers.h b/lib/csapi/read_markers.h index addb9123..0e122c63 100644 --- a/lib/csapi/read_markers.h +++ b/lib/csapi/read_markers.h @@ -17,7 +17,6 @@ class SetReadMarkerJob : public BaseJob { public: /*! \brief Set the position of the read marker for a room. * - * * \param roomId * The room ID to set the read marker in for the user. * diff --git a/lib/csapi/receipts.h b/lib/csapi/receipts.h index fdec3b88..1fac0acf 100644 --- a/lib/csapi/receipts.h +++ b/lib/csapi/receipts.h @@ -17,7 +17,6 @@ class PostReceiptJob : public BaseJob { public: /*! \brief Send a receipt for the given event ID. * - * * \param roomId * The room in which to send the event. * diff --git a/lib/csapi/redaction.h b/lib/csapi/redaction.h index c737de41..541e433a 100644 --- a/lib/csapi/redaction.h +++ b/lib/csapi/redaction.h @@ -23,7 +23,6 @@ class RedactEventJob : public BaseJob { public: /*! \brief Strips all non-integrity-critical information out of an event. * - * * \param roomId * The room from which to redact the event. * diff --git a/lib/csapi/registration.cpp b/lib/csapi/registration.cpp index 9f88ef28..b80abc84 100644 --- a/lib/csapi/registration.cpp +++ b/lib/csapi/registration.cpp @@ -82,7 +82,7 @@ RequestTokenToResetPasswordEmailJob::RequestTokenToResetPasswordEmailJob( } RequestTokenToResetPasswordMSISDNJob::RequestTokenToResetPasswordMSISDNJob( - const RequestMsisdnValidation& body) + const MsisdnValidationData& body) : BaseJob(HttpVerb::Post, QStringLiteral("RequestTokenToResetPasswordMSISDNJob"), QStringLiteral("/_matrix/client/r0") diff --git a/lib/csapi/registration.h b/lib/csapi/registration.h index 9d96db32..62bc35f1 100644 --- a/lib/csapi/registration.h +++ b/lib/csapi/registration.h @@ -4,10 +4,9 @@ #pragma once -#include "csapi/../identity/definitions/request_msisdn_validation.h" -#include "csapi/./definitions/request_email_validation.h" -#include "csapi/./definitions/request_msisdn_validation.h" #include "csapi/definitions/auth_data.h" +#include "csapi/definitions/request_email_validation.h" +#include "csapi/definitions/request_msisdn_validation.h" #include "csapi/definitions/request_token_response.h" #include "jobs/basejob.h" @@ -62,7 +61,6 @@ class RegisterJob : public BaseJob { public: /*! \brief Register for an account on this homeserver. * - * * \param kind * The kind of account to register. Defaults to ``user``. * @@ -148,7 +146,6 @@ public: /*! \brief Begins the validation process for an email to be used during * registration. * - * * \param body * The homeserver must check that the given email address is **not** * already associated with an account on this homeserver. The homeserver @@ -162,7 +159,7 @@ public: /// An email has been sent to the specified address. Note that this /// may be an email containing the validation token or it may be /// informing the user of an error. - RequestTokenResponse data() const + RequestTokenResponse response() const { return fromJson<RequestTokenResponse>(jsonData()); } @@ -181,7 +178,6 @@ public: /*! \brief Requests a validation token be sent to the given phone number for * the purpose of registering an account * - * * \param body * The homeserver must check that the given phone number is **not** * already associated with an account on this homeserver. The homeserver @@ -195,7 +191,7 @@ public: /// An SMS message has been sent to the specified phone number. Note /// that this may be an SMS message containing the validation token or /// it may be informing the user of an error. - RequestTokenResponse data() const + RequestTokenResponse response() const { return fromJson<RequestTokenResponse>(jsonData()); } @@ -221,7 +217,6 @@ class ChangePasswordJob : public BaseJob { public: /*! \brief Changes a user's password. * - * * \param newPassword * The new password for the account. * @@ -270,7 +265,6 @@ public: /*! \brief Requests a validation token be sent to the given email address * for the purpose of resetting a user's password * - * * \param body * The homeserver must check that the given email address **is * associated** with an account on this homeserver. This API should be @@ -299,7 +293,7 @@ public: // Result properties /// An email was sent to the given address. - RequestTokenResponse data() const + RequestTokenResponse response() const { return fromJson<RequestTokenResponse>(jsonData()); } @@ -333,7 +327,6 @@ public: /*! \brief Requests a validation token be sent to the given phone number for * the purpose of resetting a user's password. * - * * \param body * The homeserver must check that the given phone number **is * associated** with an account on this homeserver. This API should be @@ -357,12 +350,12 @@ public: * #post-matrix-client-r0-register-email-requesttoken */ explicit RequestTokenToResetPasswordMSISDNJob( - const RequestMsisdnValidation& body); + const MsisdnValidationData& body); // Result properties /// An SMS message was sent to the given phone number. - RequestTokenResponse data() const + RequestTokenResponse response() const { return fromJson<RequestTokenResponse>(jsonData()); } @@ -389,7 +382,6 @@ class DeactivateAccountJob : public BaseJob { public: /*! \brief Deactivate a user's account. * - * * \param auth * Additional authentication information for the user-interactive * authentication API. @@ -440,7 +432,6 @@ class CheckUsernameAvailabilityJob : public BaseJob { public: /*! \brief Checks to see if a username is available on the server. * - * * \param username * The username to check the availability of. */ diff --git a/lib/csapi/report_content.h b/lib/csapi/report_content.h index 13dc9138..375e1829 100644 --- a/lib/csapi/report_content.h +++ b/lib/csapi/report_content.h @@ -17,7 +17,6 @@ class ReportContentJob : public BaseJob { public: /*! \brief Reports an event as inappropriate. * - * * \param roomId * The room in which the event being reported is located. * diff --git a/lib/csapi/room_send.h b/lib/csapi/room_send.h index b1905e53..39460aca 100644 --- a/lib/csapi/room_send.h +++ b/lib/csapi/room_send.h @@ -22,7 +22,6 @@ class SendMessageJob : public BaseJob { public: /*! \brief Send a message event to the given room. * - * * \param roomId * The room to send the event to. * diff --git a/lib/csapi/room_state.h b/lib/csapi/room_state.h index eeb2b33c..447605ff 100644 --- a/lib/csapi/room_state.h +++ b/lib/csapi/room_state.h @@ -35,7 +35,6 @@ class SetRoomStateWithKeyJob : public BaseJob { public: /*! \brief Send a state event to the given room. * - * * \param roomId * The room to set the state in * diff --git a/lib/csapi/room_upgrades.h b/lib/csapi/room_upgrades.h index 53601816..58327587 100644 --- a/lib/csapi/room_upgrades.h +++ b/lib/csapi/room_upgrades.h @@ -16,7 +16,6 @@ class UpgradeRoomJob : public BaseJob { public: /*! \brief Upgrades a room to a new room version. * - * * \param roomId * The ID of the room to upgrade. * diff --git a/lib/csapi/rooms.h b/lib/csapi/rooms.h index 6137bcbd..f0bfa349 100644 --- a/lib/csapi/rooms.h +++ b/lib/csapi/rooms.h @@ -19,7 +19,6 @@ class GetOneRoomEventJob : public BaseJob { public: /*! \brief Get a single event by event ID. * - * * \param roomId * The ID of the room the event is in. * @@ -39,7 +38,7 @@ public: // Result properties /// The full event. - EventPtr data() { return fromJson<EventPtr>(jsonData()); } + EventPtr event() { return fromJson<EventPtr>(jsonData()); } }; /*! \brief Get the state identified by the type and key. @@ -56,7 +55,6 @@ class GetRoomStateWithKeyJob : public BaseJob { public: /*! \brief Get the state identified by the type and key. * - * * \param roomId * The room to look up the state in. * @@ -89,7 +87,6 @@ class GetRoomStateJob : public BaseJob { public: /*! \brief Get all state events in the current state of a room. * - * * \param roomId * The room to look up the state for. */ @@ -105,7 +102,7 @@ public: // Result properties /// The current state of the room - StateEvents data() { return fromJson<StateEvents>(jsonData()); } + StateEvents events() { return fromJson<StateEvents>(jsonData()); } }; /*! \brief Get the m.room.member events for the room. @@ -116,7 +113,6 @@ class GetMembersByRoomJob : public BaseJob { public: /*! \brief Get the m.room.member events for the room. * - * * \param roomId * The room to get the member events for. * @@ -190,7 +186,6 @@ public: /*! \brief Gets the list of currently joined users and their profile data. * - * * \param roomId * The room to get the members of. */ diff --git a/lib/csapi/sso_login_redirect.h b/lib/csapi/sso_login_redirect.h index 20f33da2..d6330e38 100644 --- a/lib/csapi/sso_login_redirect.h +++ b/lib/csapi/sso_login_redirect.h @@ -19,7 +19,6 @@ class RedirectToSSOJob : public BaseJob { public: /*! \brief Redirect the user's browser to the SSO interface. * - * * \param redirectUrl * URI to which the user will be redirected after the homeserver has * authenticated the user with SSO. diff --git a/lib/csapi/tags.h b/lib/csapi/tags.h index e6eb9dda..a815d9b3 100644 --- a/lib/csapi/tags.h +++ b/lib/csapi/tags.h @@ -29,7 +29,6 @@ public: /*! \brief 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. @@ -73,7 +72,6 @@ class SetRoomTagJob : public BaseJob { public: /*! \brief 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. @@ -104,7 +102,6 @@ class DeleteRoomTagJob : public BaseJob { public: /*! \brief 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. diff --git a/lib/csapi/third_party_lookup.h b/lib/csapi/third_party_lookup.h index 9329b7a7..969e767c 100644 --- a/lib/csapi/third_party_lookup.h +++ b/lib/csapi/third_party_lookup.h @@ -33,7 +33,7 @@ public: // Result properties /// The protocols supported by the homeserver. - QHash<QString, ThirdPartyProtocol> data() const + QHash<QString, ThirdPartyProtocol> protocols() const { return fromJson<QHash<QString, ThirdPartyProtocol>>(jsonData()); } @@ -50,7 +50,6 @@ public: /*! \brief Retrieve metadata about a specific protocol that the homeserver * supports. * - * * \param protocol * The name of the protocol. */ @@ -88,7 +87,6 @@ public: /*! \brief Retrieve Matrix-side portals rooms leading to a third party * location. * - * * \param protocol * The protocol used to communicate to the third party network. * @@ -125,7 +123,6 @@ class QueryUserByProtocolJob : public BaseJob { public: /*! \brief Retrieve the Matrix User ID of a corresponding third party user. * - * * \param protocol * The name of the protocol. * @@ -162,7 +159,6 @@ class QueryLocationByAliasJob : public BaseJob { public: /*! \brief Reverse-lookup third party locations given a Matrix room alias. * - * * \param alias * The Matrix room alias to look up. */ @@ -192,7 +188,6 @@ class QueryUserByIDJob : public BaseJob { public: /*! \brief Reverse-lookup third party users given a Matrix User ID. * - * * \param userid * The Matrix User ID to look up. */ diff --git a/lib/csapi/third_party_membership.h b/lib/csapi/third_party_membership.h index f8196f6f..55cab370 100644 --- a/lib/csapi/third_party_membership.h +++ b/lib/csapi/third_party_membership.h @@ -59,7 +59,6 @@ class InviteBy3PIDJob : public BaseJob { public: /*! \brief Invite a user to participate in a particular room. * - * * \param roomId * The room identifier (not alias) to which to invite the user. * diff --git a/lib/csapi/to_device.h b/lib/csapi/to_device.h index 8c82af45..f5d69d65 100644 --- a/lib/csapi/to_device.h +++ b/lib/csapi/to_device.h @@ -17,7 +17,6 @@ class SendToDeviceJob : public BaseJob { public: /*! \brief Send an event to a given set of devices. * - * * \param eventType * The type of event to send. * diff --git a/lib/csapi/typing.h b/lib/csapi/typing.h index f5b67baf..2c953949 100644 --- a/lib/csapi/typing.h +++ b/lib/csapi/typing.h @@ -19,7 +19,6 @@ class SetTypingJob : public BaseJob { public: /*! \brief Informs the server that the user has started or stopped typing. * - * * \param userId * The user who has started to type. * diff --git a/lib/csapi/users.h b/lib/csapi/users.h index adb2a33d..6fc26f57 100644 --- a/lib/csapi/users.h +++ b/lib/csapi/users.h @@ -35,7 +35,7 @@ public: /// The search is performed case-insensitively on user IDs and display /// names preferably using a collation determined based upon the /// ``Accept-Language`` header provided in the request, if present. - struct SearchUserDirectory200ThirdPartyUser { + struct User { /// The user's matrix user ID. QString userId; /// The display name of the user, if one exists. @@ -48,7 +48,6 @@ public: /*! \brief Searches the user directory. * - * * \param searchTerm * The term to search for * @@ -61,10 +60,9 @@ public: // Result properties /// Ordered by rank and then whether or not profile info is available. - QVector<SearchUserDirectory200ThirdPartyUser> results() const + QVector<User> results() const { - return loadFromJson<QVector<SearchUserDirectory200ThirdPartyUser>>( - "results"_ls); + return loadFromJson<QVector<User>>("results"_ls); } /// Indicates if the result list has been truncated by the limit. @@ -72,11 +70,9 @@ public: }; template <> -struct JsonObjectConverter< - SearchUserDirectoryJob::SearchUserDirectory200ThirdPartyUser> { - static void - fillFrom(const QJsonObject& jo, - SearchUserDirectoryJob::SearchUserDirectory200ThirdPartyUser& result) +struct JsonObjectConverter<SearchUserDirectoryJob::User> { + static void fillFrom(const QJsonObject& jo, + SearchUserDirectoryJob::User& result) { fromJson(jo.value("user_id"_ls), result.userId); fromJson(jo.value("display_name"_ls), result.displayName); |