New upstream version 0.7.0

1 files changed, 73 insertions, 65 deletions

diff --git a/lib/csapi/third_party_membership.h b/lib/csapi/third_party_membership.h
index d18fe554..1129a9a8 100644
--- a/lib/csapi/third_party_membership.h
+++ b/lib/csapi/third_party_membership.h
@@ -6,70 +6,78 @@
 
 #include "jobs/basejob.h"
 
+namespace Quotient {
 
-namespace QMatrixClient
-{
-    // Operations
+/*! \brief Invite a user to participate in a particular room.
+ *
+ * *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](/client-server-api/#post_matrixclientv3roomsroomidinvite).
+ *
+ * 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.
+ */
+class QUOTIENT_API 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.
+     *
+     * \param idServer
+     *   The hostname+port of the identity server which should be used for third
+     * party identifier lookups.
+     *
+     * \param idAccessToken
+     *   An access token previously registered with the identity server. Servers
+     *   can treat this as optional to distinguish between r0.5-compatible
+     * clients and this specification version.
+     *
+     * \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& idAccessToken,
+                             const QString& medium, const QString& address);
+};
 
-    /// 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
+} // namespace Quotient