diff options
Diffstat (limited to 'lib/csapi/third_party_membership.h')
| -rw-r--r-- | lib/csapi/third_party_membership.h | 56 |
1 files changed, 56 insertions, 0 deletions
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 |